# Cycloid Docs

> This documentation section centralize all the technical documentation and specification of Cycloid platform. Use the index on the sidebar to the left to browse each feature or use the integrated search.

- [Feature reference](/index.md)

## tags

- [Tags](/tags.md)

### feature-list

- [One doc tagged with "feature list"](/tags/feature-list.md)

### features

- [One doc tagged with "features"](/tags/features.md)

### reference

- [2 docs tagged with "reference"](/tags/reference.md)

### stackforms

- [One doc tagged with "stackforms"](/tags/stackforms.md)

### technologies

- [One doc tagged with "technologies"](/tags/technologies.md)

## cookbook

This section contains all of our tutorials, step by step guides and examples by use case.

- [Welcome to the Cycloid cookbook](/cookbook.md): This section contains all of our tutorials, step by step guides and examples by use case.

### dedicated-platform

Here, you can find comprehensive guides to set up the Cycloid platform and its dependencies. We offer two main methods for production deployment:

- [Dedicated Platform](/cookbook/dedicated-platform.md): Here, you can find comprehensive guides to set up the Cycloid platform and its dependencies. We offer two main methods for production deployment:

#### advanced-configurations

- [Advanced configurations](/cookbook/dedicated-platform/advanced-configurations.md)

##### certificate-cycloid-console

By default Cycloid generate self signed certificate to access the Console and API.

- [Adding or Updating Your Own Certificate on the Cycloid Console](/cookbook/dedicated-platform/advanced-configurations/certificate-cycloid-console.md): By default Cycloid generate self signed certificate to access the Console and API.

##### enable-cloud-cost-management

This Elasticsearch endpoint needs to respect the following requirements:

- [Enable the Cloud Cost Management feature](/cookbook/dedicated-platform/advanced-configurations/enable-cloud-cost-management.md): This Elasticsearch endpoint needs to respect the following requirements:

##### enable-cost-estimation

To enable cost-estimation, Cloud provider price need to be injested regularly.

- [Enable the Cost Estimation feature](/cookbook/dedicated-platform/advanced-configurations/enable-cost-estimation.md): To enable cost-estimation, Cloud provider price need to be injested regularly.

##### minio

MinIO is a high-performance, S3 compatible object store. It is built for large scale AI/ML, data lake and database workloads.

- [MinIO](/cookbook/dedicated-platform/advanced-configurations/minio.md): MinIO is a high-performance, S3 compatible object store. It is built for large scale AI/ML, data lake and database workloads.

##### monitoring

Services and Cycloid API Health metrics

- [Monitoring](/cookbook/dedicated-platform/advanced-configurations/monitoring.md): Services and Cycloid API Health metrics

##### redis

TLS with external Redis

- [Redis](/cookbook/dedicated-platform/advanced-configurations/redis.md): TLS with external Redis

##### smtp-configuration

Cycloid require a SMTP server to send email for invitation/notification.

- [SMTP configuration](/cookbook/dedicated-platform/advanced-configurations/smtp-configuration.md): Cycloid require a SMTP server to send email for invitation/notification.

##### unreferenced

unreferenced page

- [Advanced Configurations Unreferenced](/cookbook/dedicated-platform/advanced-configurations/unreferenced.md): unreferenced page

##### vault

MySQL storage backend

- [Vault](/cookbook/dedicated-platform/advanced-configurations/vault.md): MySQL storage backend

#### demo-poc

This section describes Self-Hosted platforms for evaluation, training or test purposes ONLY.

- [Demo - POC Self-Hosted platform](/cookbook/dedicated-platform/demo-poc.md): This section describes Self-Hosted platforms for evaluation, training or test purposes ONLY.

##### instances

Solution Description

- [Deploy on instances](/cookbook/dedicated-platform/demo-poc/instances.md): Solution Description

##### kubernetes

Solution Description

- [Deploy on Kubernetes](/cookbook/dedicated-platform/demo-poc/kubernetes.md): Solution Description

#### setup-k8s

The Cycloid on-premises setup on Kubernetes provide a way to setup the Cycloid platform and dependencies within your own Kubernetes cluster.

- [Cycloid Self-Hosted Kubernetes](/cookbook/dedicated-platform/setup-k8s.md): The Cycloid on-premises setup on Kubernetes provide a way to setup the Cycloid platform and dependencies within your own Kubernetes cluster.

#### setup-onprem

The Cycloid on-premises setup allows you to deploy the Cycloid platform and its dependencies on one or several servers using Docker.

- [Cycloid Self-Hosted Instances](/cookbook/dedicated-platform/setup-onprem.md): The Cycloid on-premises setup allows you to deploy the Cycloid platform and its dependencies on one or several servers using Docker.

### getting-started

Welcome to the Cycloid Sustainable Platform Engineering Getting Started Guide!

- [Getting started with Cycloid](/cookbook/getting-started.md): Welcome to the Cycloid Sustainable Platform Engineering Getting Started Guide!

#### devops-teams

Audience

- [Cycloid for DevOps teams](/cookbook/getting-started/devops-teams.md): Audience

##### stack-creation

As a DevOps team member, you may be interested to learn how to create and customize Cycloid Stacks. Let's first create a new Stack in your service catalog git repository.

- [Ways to create a Stack](/cookbook/getting-started/devops-teams/stack-creation.md): As a DevOps team member, you may be interested to learn how to create and customize Cycloid Stacks. Let's first create a new Stack in your service catalog git repository.

###### blueprint

Create a stack from a blueprint

- [From a stack blueprint](/cookbook/getting-started/devops-teams/stack-creation/blueprint.md): Create a stack from a blueprint

###### community

Create a stack from the Cycloid community catalog

- [From community catalog](/cookbook/getting-started/devops-teams/stack-creation/community.md): Create a stack from the Cycloid community catalog

###### import

Create a stack from an existing infrastructure

- [From existing infrastructure](/cookbook/getting-started/devops-teams/stack-creation/import.md): Create a stack from an existing infrastructure

##### stack-customization

After creating a Stack, you will want to adapt it to your specific use case. The process depends on which automation technologies you are using.

- [Customize your Stacks](/cookbook/getting-started/devops-teams/stack-customization.md): After creating a Stack, you will want to adapt it to your specific use case. The process depends on which automation technologies you are using.

###### ansible

After creating a Stack from a blueprint using Ansible, we'll explore how to customize it, including changing the Ansible playbook to your use case and exposing the variables via StackForms.

- [Using Ansible](/cookbook/getting-started/devops-teams/stack-customization/ansible.md): After creating a Stack from a blueprint using Ansible, we'll explore how to customize it, including changing the Ansible playbook to your use case and exposing the variables via StackForms.

###### helm

After creating a Stack from a blueprint using Helm, we'll explore how to customize it, including exposing the Helm charts values via StackForms. In this example, we will run the Helm chart using Terraform, so you can also add cloud infrastructure that may not be in a Kubernetes cluster, such as a managed database.

- [Using Helm charts](/cookbook/getting-started/devops-teams/stack-customization/helm.md): After creating a Stack from a blueprint using Helm, we'll explore how to customize it, including exposing the Helm charts values via StackForms. In this example, we will run the Helm chart using Terraform, so you can also add cloud infrastructure that may not be in a Kubernetes cluster, such as a managed database.

###### terraform

After creating a Stack from a blueprint using Terraform, we'll explore how to customize it, including changing the Terraform modules to your use case and exposing the variables via StackForms.

- [Using Terraform](/cookbook/getting-started/devops-teams/stack-customization/terraform.md): After creating a Stack from a blueprint using Terraform, we'll explore how to customize it, including changing the Terraform modules to your use case and exposing the variables via StackForms.

##### stackforms

After you create a Stack and you make customizations to support your use case, let's review more advanced StackForms use cases.

- [StackForms](/cookbook/getting-started/devops-teams/stackforms.md): After you create a Stack and you make customizations to support your use case, let's review more advanced StackForms use cases.

###### account

This use case allows your end-users to select a cloud account and a region from available options. If your deployment requires several accounts and/or regions, you can duplicate the same setup as required.

- [Selecting Account and Region](/cookbook/getting-started/devops-teams/stackforms/account.md): This use case allows your end-users to select a cloud account and a region from available options. If your deployment requires several accounts and/or regions, you can duplicate the same setup as required.

###### network

This use case allows your end-users to select an existing VPC and subnet, for example, to deploy new resources. The goal is to conveniently propose VPC and subnet options to the end-users.

- [Selecting VPC and subnets](/cookbook/getting-started/devops-teams/stackforms/network.md): This use case allows your end-users to select an existing VPC and subnet, for example, to deploy new resources. The goal is to conveniently propose VPC and subnet options to the end-users.
- [Dynamic data from an API endpoint](/cookbook/getting-started/devops-teams/stackforms/network/api_dynamic_values.md): This use case allows the end-user to select a VPC and one or several subnets among network resources retrieved from an external third-party API.
- [Static data from an API endpoint](/cookbook/getting-started/devops-teams/stackforms/network/api_static_values.md): This use case allows the end-user to select a VPC and one or several subnets among network resources retrieved from an external third-party API where static data is stored, typically from a cloud storage bucket.
- [From Cycloid Asset Inventory](/cookbook/getting-started/devops-teams/stackforms/network/asset_inventory.md): This use case allows the end-user to select a VPC and one or several subnets among network resources from the Cycloid Asset Inventory. It contains all resources deployed by Cycloid using Terraform within the same organization. This use case requires that a Cycloid stack using Terraform has been used to deploy the networking resources beforehand.

#### end-users

Audience

- [Cycloid for End Users](/cookbook/getting-started/end-users.md): Audience

##### deploy

Overview of Cycloid Basic Concepts

- [Create a project](/cookbook/getting-started/end-users/deploy.md): Overview of Cycloid Basic Concepts

##### user-registration

First thing first, you must have been invited by email to create your Cycloid account. If you haven't received such an email yet, please contact your Platform Team to be invited to join your Cycloid organization.

- [Create my Account](/cookbook/getting-started/end-users/user-registration.md): First thing first, you must have been invited by email to create your Cycloid account. If you haven't received such an email yet, please contact your Platform Team to be invited to join your Cycloid organization.

#### platform-teams

Audience

- [Cycloid for Platform teams](/cookbook/getting-started/platform-teams.md): Audience

##### installation

Objectives

- [Install a Self-Hosted platform](/cookbook/getting-started/platform-teams/installation.md): Objectives

##### organizations

The following section will cover the first steps to finalize the setup of your own Cycloid platform. You will set up base features in a Cycloid organization for all users of the platform.

- [Set Up an Organization](/cookbook/getting-started/platform-teams/organizations.md): The following section will cover the first steps to finalize the setup of your own Cycloid platform. You will set up base features in a Cycloid organization for all users of the platform.

###### credentials

Add your credentials to the Vault

- [Connect your Cloud](/cookbook/getting-started/platform-teams/organizations/credentials.md): Add your credentials to the Vault

###### gitops

Create your Git repository

- [GitOps set up](/cookbook/getting-started/platform-teams/organizations/gitops.md): Create your Git repository

###### organization

The concept of Organization

- [Organizations](/cookbook/getting-started/platform-teams/organizations/organization.md): The concept of Organization

###### terraform-backend

Set up a Terraform backend

- [Terraform backend](/cookbook/getting-started/platform-teams/organizations/terraform-backend.md): Set up a Terraform backend

### stacks-v4-migration

This guide is aimed toward stack maintainers. Cycloid released the Component layer feature that allows you and your users to instanciate

- [Stack v4 migration guide](/cookbook/stacks-v4-migration.md): This guide is aimed toward stack maintainers. Cycloid released the Component layer feature that allows you and your users to instanciate

## discover

Cycloid is an Engineering platform.

- [Welcome to Cycloid](/discover.md): Cycloid is an Engineering platform.

### features


#### asset-inventory

<Button

- [Asset Inventory](/discover/features/asset-inventory.md): <Button

#### ci-cd-pipelines

Cycloid CI/CD enables the creation of immutable pipelines, ensuring that each pipeline job build is based on a defined set of external resources and dependencies.

- [CI/CD Pipelines](/discover/features/ci-cd-pipelines.md): Cycloid CI/CD enables the creation of immutable pipelines, ensuring that each pipeline job build is based on a defined set of external resources and dependencies.

#### cloud-carbon-footprint

Cycloid's Cloud Carbon Footprint tool is designed to measure and analyze the environmental impact of cloud infrastructure deployments.

- [Cloud Carbon Footprint](/discover/features/cloud-carbon-footprint.md): Cycloid's Cloud Carbon Footprint tool is designed to measure and analyze the environmental impact of cloud infrastructure deployments.

#### cloud-cost-management

Cycloid's Cloud Cost Management tool empowers organizations to effectively monitor and visualize  costs associated with cloud infrastructure deployments.

- [Cloud Cost Management](/discover/features/cloud-cost-management.md): Cycloid's Cloud Cost Management tool empowers organizations to effectively monitor and visualize  costs associated with cloud infrastructure deployments.

#### connectivity-with-identity-providers

Cycloid can be used with different user authentication methods.

- [Connectivity with with identity providers](/discover/features/connectivity-with-identity-providers.md): Cycloid can be used with different user authentication methods.

#### cost-estimation

Cost Estimation provides a way for organisations to accurately forecast and predict their cloud infrastructure expenditures.

- [Cost Estimation](/discover/features/cost-estimation.md): Cost Estimation provides a way for organisations to accurately forecast and predict their cloud infrastructure expenditures.

#### credential-management

Cycloid provides robust credential management, allowing users to securely manage and store various types of credentials.

- [Credential Management](/discover/features/credential-management.md): Cycloid provides robust credential management, allowing users to securely manage and store various types of credentials.

#### infraimport

Infra Import is Cycloid's tool for automating infrastructure management through TerraCognita, our opensource tool.

- [InfraImport](/discover/features/infraimport.md): Infra Import is Cycloid's tool for automating infrastructure management through TerraCognita, our opensource tool.

#### infrapolices

Infrastructure Policies (InfraPolicy) are an implementation of Policy as Code.

- [Infrapolicies](/discover/features/infrapolices.md): Infrastructure Policies (InfraPolicy) are an implementation of Policy as Code.

#### infraview

<Button

- [Infraview](/discover/features/infraview.md): <Button

#### logs-and-events

Cycloid's Events and Logs tools allow for a quick and simple way to understand what is happening across the cycloid projects.

- [Logs and Events](/discover/features/logs-and-events.md): Cycloid's Events and Logs tools allow for a quick and simple way to understand what is happening across the cycloid projects.

#### organizations

An organization represents the highest entity level within cycloid.

- [Organizations](/discover/features/organizations.md): An organization represents the highest entity level within cycloid.

#### permissions-and-roles

Cycloid's permissions system ensures secure access control within an organization.

- [Permissions and Roles](/discover/features/permissions-and-roles.md): Cycloid's permissions system ensures secure access control within an organization.

#### saas-vs-onpremises

The choice between a SaaS or an On-premise approach to deploy cycloid, will always depend on your business requirements and your subcription.

- [SaaS vs On-premise](/discover/features/saas-vs-onpremises.md): The choice between a SaaS or an On-premise approach to deploy cycloid, will always depend on your business requirements and your subcription.

#### stackforms

StackForms allows users to configure projects through a graphical interface.

- [StackForms](/discover/features/stackforms.md): StackForms allows users to configure projects through a graphical interface.

#### stacks

<Button

- [Stacks](/discover/features/stacks.md): <Button

#### workers

A key important component to understand of cycloid architecture are the cycloid workers, based on concourse workers.

- [Workers](/discover/features/workers.md): A key important component to understand of cycloid architecture are the cycloid workers, based on concourse workers.

### opensource


#### cycloid-cli

The Cycloid CLI is a command-line interface tool designed for streamlined interaction with Cycloid's platform services.

- [Cycloid CLI](/discover/opensource/cycloid-cli.md): The Cycloid CLI is a command-line interface tool designed for streamlined interaction with Cycloid's platform services.

#### inframap

InfraMap makes manual diagrams a thing of the past by automatically building a graphical representation of your infrastructure without any input from you.

- [InfraMap](/discover/opensource/inframap.md): InfraMap makes manual diagrams a thing of the past by automatically building a graphical representation of your infrastructure without any input from you.

#### terracognita

TerraCognita is our open-source “reverse” Terraform.

- [Terracognita](/discover/opensource/terracognita.md): TerraCognita is our open-source “reverse” Terraform.

#### terracost

TerraCost automatically gives you insight into the total cost of your deployments - before you actually deploy them.

- [Terracost](/discover/opensource/terracost.md): TerraCost automatically gives you insight into the total cost of your deployments - before you actually deploy them.

## reference

This is the feature reference of Cycloid.


- [Feature reference](/reference.md): This is the feature reference of Cycloid.


### api

Introduction

- [API](/reference/api.md): Introduction

### ci-cd-pipelines

Introduction

- [CI/CD pipelines](/reference/ci-cd-pipelines.md): Introduction

#### concepts


##### cycloid-toolkit

Overview

- [Cycloid toolkit](/reference/ci-cd-pipelines/concepts/cycloid-toolkit.md): Overview

##### interface

Pipeline

- [Interface](/reference/ci-cd-pipelines/concepts/interface.md): Pipeline

##### pipeline

In this section, we will go through basic pipeline components and formats before moving on to more advanced tips.

- [Pipeline](/reference/ci-cd-pipelines/concepts/pipeline.md): In this section, we will go through basic pipeline components and formats before moving on to more advanced tips.

##### pipelines-overview

Overview

- [Pipelines Overview](/reference/ci-cd-pipelines/concepts/pipelines-overview.md): Overview

##### tools-integration

This section provides comprehensive information and examples on integrating various common technologies into pipelines.

- [Tools integration](/reference/ci-cd-pipelines/concepts/tools-integration.md): This section provides comprehensive information and examples on integrating various common technologies into pipelines.

###### ansible

Integrating Ansible into a Cycloid pipeline is facilitated by the ansible-runner script available in the cycloid/cycloid-toolkit Docker image.

- [Ansible](/reference/ci-cd-pipelines/concepts/tools-integration/ansible.md): Integrating Ansible into a Cycloid pipeline is facilitated by the ansible-runner script available in the cycloid/cycloid-toolkit Docker image.

###### interpolation

Cycloid introduced a

- [Interpolation](/reference/ci-cd-pipelines/concepts/tools-integration/interpolation.md): Cycloid introduced a

###### terraform

To run Terraform within a pipeline, we typically recommend following the stack concept and leveraging the community Concourse Terraform resource.

- [Terraform](/reference/ci-cd-pipelines/concepts/tools-integration/terraform.md): To run Terraform within a pipeline, we typically recommend following the stack concept and leveraging the community Concourse Terraform resource.

##### workers

A Cycloid worker is an essential component that executes the tasks defined in a pipelines.

- [Workers](/reference/ci-cd-pipelines/concepts/workers.md): A Cycloid worker is an essential component that executes the tasks defined in a pipelines.

###### aws

The CloudFormation deployment is based on a template located under our stack-external-worker git repository.

- [On Amazon Web Services with CloudFormation](/reference/ci-cd-pipelines/concepts/workers/aws.md): The CloudFormation deployment is based on a template located under our stack-external-worker git repository.

###### azure

The Azure Resource Manager template is located under our stack-external-worker git repository.

- [On Microsoft Azure with Resource Manager Template](/reference/ci-cd-pipelines/concepts/workers/azure.md): The Azure Resource Manager template is located under our stack-external-worker git repository.

###### baremetal

To run a Cycloid worker on a bare metal or on-premises server, it is currently required to provide a debian-based operating system.

- [Deploy a baremetal Cycloid worker](/reference/ci-cd-pipelines/concepts/workers/baremetal.md): To run a Cycloid worker on a bare metal or on-premises server, it is currently required to provide a debian-based operating system.

###### docker

This solution is for DEVELOPMENT PURPOSES ONLY. For production worker, we advice you to use the dedicated setup for each cloud providers.

- [Deploy a local Cycloid worker using Docker](/reference/ci-cd-pipelines/concepts/workers/docker.md): This solution is for DEVELOPMENT PURPOSES ONLY. For production worker, we advice you to use the dedicated setup for each cloud providers.

###### flexible-engine

Download our Flexible engine Resource Template flexible-engine.zip S3 bucket.

- [On Flexible engine with Resource Template Service (RTS)](/reference/ci-cd-pipelines/concepts/workers/flexible-engine.md): Download our Flexible engine Resource Template flexible-engine.zip S3 bucket.

###### gcp

The Deployment manager is based on a template located under our stack-external-worker git repository.

- [On Google Cloud Platform with Deployment manager](/reference/ci-cd-pipelines/concepts/workers/gcp.md): The Deployment manager is based on a template located under our stack-external-worker git repository.

###### known-errors

Related to this bug https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=998716 on some Cloud provider Debian 12 image is not fully working.

- [Cycloid workers known errors](/reference/ci-cd-pipelines/concepts/workers/known-errors.md): Related to this bug https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=998716 on some Cloud provider Debian 12 image is not fully working.

###### troubleshooting

Basics

- [Troubleshooting](/reference/ci-cd-pipelines/concepts/workers/troubleshooting.md): Basics

#### examples


##### snippets

How to cleanup old Amazon AMI after a build

- [Snippets](/reference/ci-cd-pipelines/examples/snippets.md): How to cleanup old Amazon AMI after a build

#### references


##### common-errors-troubleshooting

Common pipeline errors

- [Common errors / troubleshooting](/reference/ci-cd-pipelines/references/common-errors-troubleshooting.md): Common pipeline errors

##### pipeline-style-guide

Reduce log outputs

- [Pipeline style guide](/reference/ci-cd-pipelines/references/pipeline-style-guide.md): Reduce log outputs

### cli

Introduction

- [Cycloid CLI](/reference/cli.md): Introduction

#### concepts


##### cycloid_uri_references

The Cycloid CLI can resolve Cycloid URI references to either fetch or

- [Cycloid URI References](/reference/cli/concepts/cycloid_uri_references.md): The Cycloid CLI can resolve Cycloid URI references to either fetch or

#### examples

Create an component using stackforms

- [Examples](/reference/cli/examples.md): Create an component using stackforms

### cloud-carbon-footprint

- [Cloud carbon footprint](/reference/cloud-carbon-footprint.md)

### cloud-cost-management

Introduction

- [Cloud Cost Management](/reference/cloud-cost-management.md): Introduction

#### concepts


##### ccm-accounts

You can check the CCM accounts by clicking on the Accounts tab on the top bar of the feature. Here you can have an overview of all the CCM accounts.

- [Accounts](/reference/cloud-cost-management/concepts/ccm-accounts.md): You can check the CCM accounts by clicking on the Accounts tab on the top bar of the feature. Here you can have an overview of all the CCM accounts.

##### ccm-dashboard

The Cloud Cost Manager dashboard is the core of this feature. It's where you're able to see the agregated data of all your accounts and by using a set of different views have a more detailed look into it as you may require.

- [Dashboard](/reference/cloud-cost-management/concepts/ccm-dashboard.md): The Cloud Cost Manager dashboard is the core of this feature. It's where you're able to see the agregated data of all your accounts and by using a set of different views have a more detailed look into it as you may require.

##### tag-mapping

You can check the CCM accounts by clicking on the Accounts tab on the top bar of the feature.

- [Tag mapping](/reference/cloud-cost-management/concepts/tag-mapping.md): You can check the CCM accounts by clicking on the Accounts tab on the top bar of the feature.

### config-and-catalog-repository

Introduction

- [Config and catalog repositories](/reference/config-and-catalog-repository.md): Introduction

### cost-estimation

Introduction

- [Cost estimation](/reference/cost-estimation.md): Introduction

### credentials

See for yourself on the next section.

- [Credentials](/reference/credentials.md): See for yourself on the next section.

#### concepts

Credential types

- [Concepts](/reference/credentials/concepts.md): Credential types

#### examples


##### using-the-api

Create a credential

- [Manipulate credentials using the API](/reference/credentials/examples/using-the-api.md): Create a credential

##### using-the-cli

Create a credential

- [Manipulate credentials using the CLI](/reference/credentials/examples/using-the-cli.md): Create a credential

#### quickstart

Interface

- [Quickstart](/reference/credentials/quickstart.md): Interface

### dedicated-platform

Introduction

- [Dedicated Platform](/reference/dedicated-platform.md): Introduction

#### troubleshooting

Cycloid API

- [Troubleshooting](/reference/dedicated-platform/troubleshooting.md): Cycloid API

### events

Introduction

- [Events](/reference/events.md): Introduction

#### concepts

Interface

- [Concepts](/reference/events/concepts.md): Interface

#### examples


##### cli

Right now, the CLI can only create events, this is a limitation that will be addressed in future updates.

- [Using the CLI](/reference/events/examples/cli.md): Right now, the CLI can only create events, this is a limitation that will be addressed in future updates.

##### concourse-resource

Links:

- [Using the Cycloid concourse resource](/reference/events/examples/concourse-resource.md): Links:

##### event-api

Those are examples for practical uses.

- [Using the API](/reference/events/examples/event-api.md): Those are examples for practical uses.

### infra-import

Introduction

- [Infra Import](/reference/infra-import.md): Introduction

#### quickstart

Infra Import needs some upfront configuration to be able to fetch the right resources for you, see the previous prerequisites section if not already done.

- [Quickstart](/reference/infra-import/quickstart.md): Infra Import needs some upfront configuration to be able to fetch the right resources for you, see the previous prerequisites section if not already done.

### infrapolicies-policy-as-code

Introduction

- [Infrapolicies - policy as code](/reference/infrapolicies-policy-as-code.md): Introduction

#### concepts

- [Concepts](/reference/infrapolicies-policy-as-code/concepts.md)

#### reference

- [Reference](/reference/infrapolicies-policy-as-code/reference.md)

### infraview

Introduction

- [InfraView](/reference/infraview.md): Introduction

#### concepts

Interface

- [Concepts](/reference/infraview/concepts.md): Interface

### inventory

Introduction

- [Asset Inventory](/reference/inventory.md): Introduction

#### concepts

Dashboard

- [Concepts](/reference/inventory/concepts.md): Dashboard

#### reference

Use Cycloid Terraform HTTP backend in a pipeline

- [Reference](/reference/inventory/reference.md): Use Cycloid Terraform HTTP backend in a pipeline

### legacy-doc

This section contains legacy docs we saved and are going to migrate

- [legacy docs](/reference/legacy-doc.md): This section contains legacy docs we saved and are going to migrate

#### create-my-first-stack


##### intro

<!--

- [Create my first Stack](/reference/legacy-doc/create-my-first-stack/intro.md): <!--

##### prepare-cycloid-credentials

Let's create Cycloid credentials that we will use in our pipeline. Click on Credentials under Security in the left menu.

- [Prepare Cycloid credentials](/reference/legacy-doc/create-my-first-stack/prepare-cycloid-credentials.md): Let's create Cycloid credentials that we will use in our pipeline. Click on Credentials under Security in the left menu.

##### requirements

To simplify the step by step guide, we assume that you provide the following elements:

- [Requirements](/reference/legacy-doc/create-my-first-stack/requirements.md): To simplify the step by step guide, we assume that you provide the following elements:

##### step1

In this guide, we will deploy an HTML website on a cloud instance.

- [Application source code](/reference/legacy-doc/create-my-first-stack/step1.md): In this guide, we will deploy an HTML website on a cloud instance.

##### step2-part1

* Check out the git diff of this step here.

- [Initiate a stacks branch with a basic pipeline](/reference/legacy-doc/create-my-first-stack/step2-part1.md): * Check out the git diff of this step here.

##### step2-part2

Create a config branch in your git repository

- [Step 2 part 2 - Use a stack](/reference/legacy-doc/create-my-first-stack/step2-part2.md): Create a config branch in your git repository

##### step3

* Check out the git diff of this step here.

- [Configure the pipeline to run Terraform plan](/reference/legacy-doc/create-my-first-stack/step3.md): * Check out the git diff of this step here.

##### step4

* Check out the git diff of this step here.

- [Create a Terraform module and add Terraform apply job in the pipeline](/reference/legacy-doc/create-my-first-stack/step4.md): * Check out the git diff of this step here.

##### step5

This section introduce Cycloid stacks concept to improve the reusability of your stack.

- [Move module call to config branch and specify Terraform sample into .cycloid.yml](/reference/legacy-doc/create-my-first-stack/step5.md): This section introduce Cycloid stacks concept to improve the reusability of your stack.

##### step6

* Check out the git diff of this step here.

- [Add functional tests using Terraform outputs to get instance IP address](/reference/legacy-doc/create-my-first-stack/step6.md): * Check out the git diff of this step here.

##### step7

* Check out the git diff of this step here.

- [Generate notifications, using Cycloid events as example](/reference/legacy-doc/create-my-first-stack/step7.md): * Check out the git diff of this step here.

##### step8

* Check out the git diff of this step here.

- [Using StackForms to simplify the configuration](/reference/legacy-doc/create-my-first-stack/step8.md): * Check out the git diff of this step here.

##### step9

* Check out the git diff of this step here.

- [Add cleanup job to remove everything that have been created on your cloud provider by Terraform](/reference/legacy-doc/create-my-first-stack/step9.md): * Check out the git diff of this step here.

#### get-started

Let's have a tour together around all Cycloid features. Starting from account creation, stack deployment for you to master our ecosystem in no time.

- [Overview](/reference/legacy-doc/get-started.md): Let's have a tour together around all Cycloid features. Starting from account creation, stack deployment for you to master our ecosystem in no time.

##### account-creation

Get 1 week's access to our sandbox environment

- [Account creation (SaaS only)](/reference/legacy-doc/get-started/account-creation.md): Get 1 week's access to our sandbox environment

##### configuration

At Cycloid, we strive to use Git as much as possible to store infrastructure as code, automation, and configuration.

- [Configuration](/reference/legacy-doc/get-started/configuration.md): At Cycloid, we strive to use Git as much as possible to store infrastructure as code, automation, and configuration.

##### deploy

Today there are 2 ways to start a new project in Cycloid:

- [Deploy](/reference/legacy-doc/get-started/deploy.md): Today there are 2 ways to start a new project in Cycloid:

##### manage

After creating a project environment, the corresponding pipeline will be displayed. The purpose of this pipeline is to manage the entire workflow, from testing and building the source code to deploying it in production, as well as notifications, creating the target infrastructure, and any other step you can imagine.

- [Manage](/reference/legacy-doc/get-started/manage.md): After creating a project environment, the corresponding pipeline will be displayed. The purpose of this pipeline is to manage the entire workflow, from testing and building the source code to deploying it in production, as well as notifications, creating the target infrastructure, and any other step you can imagine.

#### pipeline-training

*  ] [Stack concept

- [Pipeline training support](/reference/legacy-doc/pipeline-training.md): *  ] [Stack concept

#### terraform-training

[[toc]]

- [Terraform training support](/reference/legacy-doc/terraform-training.md): [[toc]]

### notifications

Notifications provide timely updates on Cycloid activity, allowing users to stay informed about changes or events.

- [Notifications](/reference/notifications.md): Notifications provide timely updates on Cycloid activity, allowing users to stay informed about changes or events.

### organizations

Introduction

- [Organizations](/reference/organizations.md): Introduction

#### concepts


##### authentication

Overview

- [Authentication](/reference/organizations/concepts/authentication.md): Overview

##### child_organizations

Organizations can have child organizations. This can be useful to manage project and permissions

- [Child organizations](/reference/organizations/concepts/child_organizations.md): Organizations can have child organizations. This can be useful to manage project and permissions

##### interface

You current organization is displayed on the top right corner of the interface:

- [Interface](/reference/organizations/concepts/interface.md): You current organization is displayed on the top right corner of the interface:

##### licencing

Overview

- [Licensing](/reference/organizations/concepts/licencing.md): Overview

##### permissions

Cycloid platform include a fine tune policy based permission management. Each permission

- [Permissions](/reference/organizations/concepts/permissions.md): Cycloid platform include a fine tune policy based permission management. Each permission

##### workers

CI/CD workers for pipelines in cycloid are scoped by organization.

- [Workers](/reference/organizations/concepts/workers.md): CI/CD workers for pipelines in cycloid are scoped by organization.

### oss

Cycloid is built upon Open Source software. It is in our DNA and we contribute as much as we can to the OSS ecosystem.

- [Open Source Software](/reference/oss.md): Cycloid is built upon Open Source software. It is in our DNA and we contribute as much as we can to the OSS ecosystem.

#### inframap

- Github Repository & Readme

- [InfraMap](/reference/oss/inframap.md): - Github Repository & Readme

#### mcp-server

The Cycloid Model Context Protocol (MCP) Server is a powerful tool that acts as a bridge, enabling Large Language Models (LLMs)—like those powering Claude, Cursor, or GitHub Copilot—to interact directly with your Cycloid instance. This allows you to leverage natural language to query your infrastructure, manage resources, and streamline your development workflows, all from your preferred interfaces.

- [Cycloid MCP Server](/reference/oss/mcp-server.md): The Cycloid Model Context Protocol (MCP) Server is a powerful tool that acts as a bridge, enabling Large Language Models (LLMs)—like those powering Claude, Cursor, or GitHub Copilot—to interact directly with your Cycloid instance. This allows you to leverage natural language to query your infrastructure, manage resources, and streamline your development workflows, all from your preferred interfaces.

#### terracognita

- Github Repository & Readme

- [TerraCognita](/reference/oss/terracognita.md): - Github Repository & Readme

#### terracost

- GitHub Repository

- [TerraCost](/reference/oss/terracost.md): - GitHub Repository

### projects

Projects are the main entity that allows you to use Cycloid.

- [Projects](/reference/projects.md): Projects are the main entity that allows you to use Cycloid.

#### concepts


##### components

Creating a component

- [Components](/reference/projects/concepts/components.md): Creating a component

##### environments

Most of the time, the environment name and project name in Cycloid are passed as input variables to infrastructure as code. This enables them to be used as tags on cloud resources, ensuring clear identification and organization of resources across different environments and projects.

- [Environments](/reference/projects/concepts/environments.md): Most of the time, the environment name and project name in Cycloid are passed as input variables to infrastructure as code. This enables them to be used as tags on cloud resources, ensuring clear identification and organization of resources across different environments and projects.

##### interface

Global

- [Interface](/reference/projects/concepts/interface.md): Global

##### logs

Applications and infrastructure logs stored in a compatible backend can be displayed in Cycloid, offering a convenient and centralized way to monitor your application after deployment.

- [Logs](/reference/projects/concepts/logs.md): Applications and infrastructure logs stored in a compatible backend can be displayed in Cycloid, offering a convenient and centralized way to monitor your application after deployment.

##### metrics

In the Metrics tab, you can view and configure Key Performance Indicators (KPIs) to gain insights into your pipelines, jobs, deployments, code coverage, and more.

- [Metrics](/reference/projects/concepts/metrics.md): In the Metrics tab, you can view and configure Key Performance Indicators (KPIs) to gain insights into your pipelines, jobs, deployments, code coverage, and more.

##### scheduling

The scheduling feature allows you to optimize costs by automatically starting and stopping cloud resources for specific components.

- [Scheduling](/reference/projects/concepts/scheduling.md): The scheduling feature allows you to optimize costs by automatically starting and stopping cloud resources for specific components.

#### cookbook


##### migrate_component

In Cycloid, it's possible to move a component from one project to another. In most cases, it's easier and cleaner to simply delete and recreate the component. However, in specific scenarios, you may need to force the migration of an existing component.

- [Migrating a Component from One Project to Another](/reference/projects/cookbook/migrate_component.md): In Cycloid, it's possible to move a component from one project to another. In most cases, it's easier and cleaner to simply delete and recreate the component. However, in specific scenarios, you may need to force the migration of an existing component.

##### migrate_project

This doc is based before component layer feature. Main workflow could be applied with components. But few things need to be adapted.

- [Migrating an Environment from One Project to Another](/reference/projects/cookbook/migrate_project.md): This doc is based before component layer feature. Main workflow could be applied with components. But few things need to be adapted.

### stack-blueprint

Quickstart

- [Stack Blueprints](/reference/stack-blueprint.md): Quickstart

#### concepts

Writing your own blueprints

- [Concepts](/reference/stack-blueprint/concepts.md): Writing your own blueprints

#### reference

Variables

- [Reference](/reference/stack-blueprint/reference.md): Variables

### stackforms

- [Stackforms](/reference/stackforms.md)

#### concepts


##### common-use-case

As described in the file format page, if you are working with a stack containing several use cases, each use case has to be defined in StackForms.

- [Common use case](/reference/stackforms/concepts/common-use-case.md): As described in the file format page, if you are working with a stack containing several use cases, each use case has to be defined in StackForms.

##### conditions

Group-condition

- [Conditions](/reference/stackforms/concepts/conditions.md): Group-condition

##### dynamic-values

This section cover how to create forms filled with dynamic values using the values_ref attribute.

- [Dynamic values](/reference/stackforms/concepts/dynamic-values.md): This section cover how to create forms filled with dynamic values using the values_ref attribute.

##### forms-file

The Stackform definition is contained in a file called .forms.yml, located at the same location as your .cycloid.yml file.

- [.forms file](/reference/stackforms/concepts/forms-file.md): The Stackform definition is contained in a file called .forms.yml, located at the same location as your .cycloid.yml file.

##### technologies

As described, StackForms creates a link between Infrastructure as Code (IaC) variables and HTML forms.

- [Technologies](/reference/stackforms/concepts/technologies.md): As described, StackForms creates a link between Infrastructure as Code (IaC) variables and HTML forms.

##### value-mapping

Sometimes, when using a form, you may prefer to display text instead of specific values, especially if the values are not very clear to users. For instance, you might want to simplify cloud provider instance types by displaying L instead of m5.large.

- [Map value mapping](/reference/stackforms/concepts/value-mapping.md): Sometimes, when using a form, you may prefer to display text instead of specific values, especially if the values are not very clear to users. For instance, you might want to simplify cloud provider instance types by displaying L instead of m5.large.

##### value-validations

This attribute provides comprehensive validation options, including regular expression (RegExp) patterns for the simpletext widget, and specific key and element validations for the textarea widget.

- [Validation](/reference/stackforms/concepts/value-validations.md): This attribute provides comprehensive validation options, including regular expression (RegExp) patterns for the simpletext widget, and specific key and element validations for the textarea widget.

##### variables

In Stackforms, a variable defines the mapping between a specific variable in an Infrastructure as Code technology (e.g., Pipeline, Ansible, Terraform, etc.) and an HTML widget displayed to a user.

- [Variables](/reference/stackforms/concepts/variables.md): In Stackforms, a variable defines the mapping between a specific variable in an Infrastructure as Code technology (e.g., Pipeline, Ansible, Terraform, etc.) and an HTML widget displayed to a user.

##### widgets

Available Widgets

- [Widgets](/reference/stackforms/concepts/widgets.md): Available Widgets

##### yaml-anchor-and-aliases

If the common use case feature (cycloid-common use case) isn't sufficient for your needs, you can still leverage YAML's native features to tailor your configurations.

- [YAML Anchors and Aliases](/reference/stackforms/concepts/yaml-anchor-and-aliases.md): If the common use case feature (cycloid-common use case) isn't sufficient for your needs, you can still leverage YAML's native features to tailor your configurations.

#### examples


##### file-reference

- [File reference example](/reference/stackforms/examples/file-reference.md)

##### using-the-cli

Starting at Cycloid CLI version >= 5.0.49 you can now manipulate environments in projects

- [Manipulate Stackforms environments using the CLI](/reference/stackforms/examples/using-the-cli.md): Starting at Cycloid CLI version >= 5.0.49 you can now manipulate environments in projects

#### introduction

The .forms.yml file allows for the creation (or update) of a project via a nice interface, enabling easier and more controlled configuration of stacks. This includes restrictions on provided values, exposed variables, range, etc.

- [Introduction](/reference/stackforms/introduction.md): The .forms.yml file allows for the creation (or update) of a project via a nice interface, enabling easier and more controlled configuration of stacks. This includes restrictions on provided values, exposed variables, range, etc.

#### quickstart

This quick start section provides a "Hello World" example by adding Stackforms to an existing private stack.

- [Quickstart](/reference/stackforms/quickstart.md): This quick start section provides a "Hello World" example by adding Stackforms to an existing private stack.

#### reference


##### editor

Writing a StackForms file can be a lengthy and sometimes tedious process, involving back-and-forth between your Git repository and creating a project with such a file.

- [Editor](/reference/stackforms/reference/editor.md): Writing a StackForms file can be a lengthy and sometimes tedious process, involving back-and-forth between your Git repository and creating a project with such a file.

##### types

What widget are available depending on the output type you need.

- [Types](/reference/stackforms/reference/types.md): What widget are available depending on the output type you need.

##### widgets

Define pipeline variables

- [Widgets](/reference/stackforms/reference/widgets.md): Define pipeline variables

###### auto_complete

The autocomplete widget is similar to a dropdown but allows users to provide their own values in addition to selecting from predefined options.

- [auto_complete](/reference/stackforms/reference/widgets/auto_complete.md): The autocomplete widget is similar to a dropdown but allows users to provide their own values in addition to selecting from predefined options.

###### cy_branch

This widget must be used with either cyscs or cycrs. Its purpose is to expose available Git branches in Catalog or Config Git repositories.

- [cy_branch](/reference/stackforms/reference/widgets/cy_branch.md): This widget must be used with either cyscs or cycrs. Its purpose is to expose available Git branches in Catalog or Config Git repositories.

###### cy_cred

The credential widget assists users in selecting Cycloid credentials. This widget outputs a credential path, which combines the canonical name with a specific field.

- [cy_cred](/reference/stackforms/reference/widgets/cy_cred.md): The credential widget assists users in selecting Cycloid credentials. This widget outputs a credential path, which combines the canonical name with a specific field.

###### cy_crs

Similar to the cysrs widget, cycrs exposes available Cycloid config repositories. When selected, it returns the Git URL of the config repository.

- [cy_crs](/reference/stackforms/reference/widgets/cy_crs.md): Similar to the cysrs widget, cycrs exposes available Cycloid config repositories. When selected, it returns the Git URL of the config repository.

###### cy_inventory_resource

The inventory widget integrates with Cycloid's Asset inventory feature. It enables users to create a resource selector within a form, automatically populating resources from their Inventory based on predefined filtering criteria in the form's YAML syntax. This streamlines the form submission process by simplifying resource selection.

- [cy_inventory_resource](/reference/stackforms/reference/widgets/cy_inventory_resource.md): The inventory widget integrates with Cycloid's Asset inventory feature. It enables users to create a resource selector within a form, automatically populating resources from their Inventory based on predefined filtering criteria in the form's YAML syntax. This streamlines the form submission process by simplifying resource selection.

###### cy_scs

Expose Cycloid catalog repositories available. When selected, it will return the Git URL of the catalog repository.

- [cy_scs](/reference/stackforms/reference/widgets/cy_scs.md): Expose Cycloid catalog repositories available. When selected, it will return the Git URL of the catalog repository.

###### dropdown

The dropdown widget provides users with the option to choose from predefined values.

- [dropdown](/reference/stackforms/reference/widgets/dropdown.md): The dropdown widget provides users with the option to choose from predefined values.

###### number

widget

- [number](/reference/stackforms/reference/widgets/number.md): widget

###### radios

widget

- [radios](/reference/stackforms/reference/widgets/radios.md): widget

###### simple_text

widget

- [simple_text](/reference/stackforms/reference/widgets/simple_text.md): widget

###### slider_list

widget

- [slider_list](/reference/stackforms/reference/widgets/slider_list.md): widget

###### slider_range

widget

- [slider_range](/reference/stackforms/reference/widgets/slider_range.md): widget

###### switch

widget

- [switch](/reference/stackforms/reference/widgets/switch.md): widget

###### text_area

The text area widget allows users to input various types of data, such as maps, arrays, or multiline text. It provides a large space for free-form text, and can also be used to allow users to provide samples or scripts, such as userdata for cloud init.

- [text_area](/reference/stackforms/reference/widgets/text_area.md): The text area widget allows users to input various types of data, such as maps, arrays, or multiline text. It provides a large space for free-form text, and can also be used to allow users to provide samples or scripts, such as userdata for cloud init.

### stacks

Introduction

- [Stacks](/reference/stacks.md): Introduction

#### concepts


##### design-stack

After grasping the concept of stacks composed of the stack and config parts,

- [Design a stack](/reference/stacks/concepts/design-stack.md): After grasping the concept of stacks composed of the stack and config parts,

##### iac-and-gitops

Cycloid stacks follow 2 main concepts, GitOps and Infrastructure as code (IaC). Before going more in details about stack it's important to understand those both approach.

- [Infrastructure as code and GitOps](/reference/stacks/concepts/iac-and-gitops.md): Cycloid stacks follow 2 main concepts, GitOps and Infrastructure as code (IaC). Before going more in details about stack it's important to understand those both approach.

##### stack-concept

On top of the technical aspects of a stack described in the previous sections,

- [Stack concept](/reference/stacks/concepts/stack-concept.md): On top of the technical aspects of a stack described in the previous sections,

##### stack-definition

As previously defined, a Stack in Cycloid is a crucial component that follows the infrastructure as code approach,

- [Stack definition](/reference/stacks/concepts/stack-definition.md): As previously defined, a Stack in Cycloid is a crucial component that follows the infrastructure as code approach,

##### templating

Cycloid special vars to use with a templating language.

Usable in .forms.yml, .cycloid.yml, pipelines, terraform and ansible sample files.


- [Templating](/reference/stacks/concepts/templating.md): Cycloid special vars to use with a templating language.

Usable in .forms.yml, .cycloid.yml, pipelines, terraform and ansible sample files.


##### use-cases

What is a stack use case?

- [Use-cases](/reference/stacks/concepts/use-cases.md): What is a stack use case?

#### examples


##### stack-examples

This section cover several example on how we solved various usecases using stacks and pipelines. It will provide design approach and idea on doing things

- [Stack Examples](/reference/stacks/examples/stack-examples.md): This section cover several example on how we solved various usecases using stacks and pipelines. It will provide design approach and idea on doing things

##### templating-examples

This section cover several example on how we use templating in our Stacks.

- [Stack Templating Examples](/reference/stacks/examples/templating-examples.md): This section cover several example on how we use templating in our Stacks.

#### reference


##### cycloid-file

The .cycloid.yml is the main item of the Stack definition.

- [.cycloid file](/reference/stacks/reference/cycloid-file.md): The .cycloid.yml is the main item of the Stack definition.

##### dev-env-stacks

This section is comming soon. Right now in few lines to write a new stack we would advice to use stack blueprint feature.

- [Setup dev env for stacks](/reference/stacks/reference/dev-env-stacks.md): This section is comming soon. Right now in few lines to write a new stack we would advice to use stack blueprint feature.

##### link-stacks-with-terraform

Sometimes it's useful to establish connections or "links" between different stacks.

- [Linking Stacks with Terraform](/reference/stacks/reference/link-stacks-with-terraform.md): Sometimes it's useful to establish connections or "links" between different stacks.

##### manually-run-terraform

Sometimes, it could be useful to run Terraform commands manually from a stack's source code, for tasks such as syntax validation. For example:

- [Manual Run of Terraform Code](/reference/stacks/reference/manually-run-terraform.md): Sometimes, it could be useful to run Terraform commands manually from a stack's source code, for tasks such as syntax validation. For example:

##### override-stack-with-config

If you're using a Cycloid stack or one based on a Cycloid template, it should adhere to the Concept of a Stack.

- [Override a Stack with Config at Merge](/reference/stacks/reference/override-stack-with-config.md): If you're using a Cycloid stack or one based on a Cycloid template, it should adhere to the Concept of a Stack.

##### public-and-community-stacks

If you are looking for additional stacks, Cycloid provides a few divided into two categories: Public and Community Stacks.

- [Public and Community Stacks](/reference/stacks/reference/public-and-community-stacks.md): If you are looking for additional stacks, Cycloid provides a few divided into two categories: Public and Community Stacks.

##### special-variables

- [Special variables](/reference/stacks/reference/special-variables.md)

##### terraform-upgrade

This tutorial gives you some tips on how to upgrade the Terraform used in cycloid's stacks, to the latest version (at the moment of writing terraform v1).

- [Upgrade Terraform code](/reference/stacks/reference/terraform-upgrade.md): This tutorial gives you some tips on how to upgrade the Terraform used in cycloid's stacks, to the latest version (at the moment of writing terraform v1).


---

# Full Documentation Content

## F[​](#F "Direct link to F")

* [feature list1](/tags/feature-list.md)
* [features1](/tags/features.md)

***


---

## [Feature reference](/reference.md)

This is the feature reference of Cycloid.


---

## [Feature reference](/reference.md)

This is the feature reference of Cycloid.


---

## [Feature reference](/reference.md)

This is the feature reference of Cycloid.


---

## [Technologies](/reference/stackforms/concepts/technologies.md)

As described, StackForms creates a link between Infrastructure as Code (IaC) variables and HTML forms.


---

## [Technologies](/reference/stackforms/concepts/technologies.md)

As described, StackForms creates a link between Infrastructure as Code (IaC) variables and HTML forms.


---

# Welcome to the Cycloid cookbook

This section contains all of our tutorials, step by step guides and examples by use case. These are meant to guide you in a more intuitive way.

To get more direct technical information or in depth explanation, check the [reference section](/reference.md).

Here is a list of guides you will find in this section:

| Section                                                               | Synopsis                                                   |
| --------------------------------------------------------------------- | ---------------------------------------------------------- |
| [Getting started with Cycloid](/cookbook/getting-started/.md)         | A quick introduction to the common uses of our platform.   |
| [Setup your own dedicated platform](/cookbook/dedicated-platform/.md) | Guide on how to setup your own dedicated Cycloid platform. |


---

# Dedicated Platform

Here, you can find comprehensive guides to set up the Cycloid platform and its dependencies. We offer two main methods for **production deployment**:

* [**Kubernetes Cluster**](/cookbook/dedicated-platform/setup-k8s.md): Set up the Cycloid platform and dependencies within your own Kubernetes cluster.
* [**Baremetal Servers or Cloud Instances**](/cookbook/dedicated-platform/setup-onprem.md): Set up the Cycloid platform and dependencies on one or several servers using Docker.

If you are looking for an evaluation platform (for Demo, POC purposes only) you might want to follow the [POC Self-Hosted platform](/cookbook/dedicated-platform/demo-poc/.md) guide.

Choose the appropriate guide to get started with your preferred deployment method.


---

# Advanced configurations


---

# Adding or Updating Your Own Certificate on the Cycloid Console

* Cycloid Self-Hosted Instances
* Cycloid Self-Hosted Kubernetes

By default Cycloid generate self signed certificate to access the Console and API. If you need to use a public or trusted certificate, please follow those steps:

**1/** From your `cycloid-onprem` installation directory, copy your certificate (crt) and private key (key) files under the following path

```
datas/ssl/cycloid-core.crt
datas/ssl/cycloid-core.key
```

**2/** Update Cycloid certificate by running [Cycloid Upgrade](/cookbook/dedicated-platform/setup-onprem.md#upgrade)

Kubernetes secrets can be used to provide certificates to your Ingress resources. This ensures secure HTTPS communication by managing TLS/SSL certificates.

Here is an example of how to create a Kubernetes secret containing HTTPS/TLS certificates using the **kubectl** command-line tool:

Ensure you have the following files ready:

* **tls.crt**: The TLS certificate file.
* **tls.key**: The private key file.

Creates a secret named cycloid-local-tls containing your TLS certificate and key.

```
kubectl create secret tls cycloid-local-tls --cert=tls.crt --key=tls.key
```

You can then utilize this secret within your `values.custom.yaml` to enable HTTPS for the Ingress resources:

```
frontend:
  ingress:
    enabled: true
    hosts:
      - host: console.cycloid.local
        paths:
          - path: /
            pathType: ImplementationSpecific
    tls:
    - secretName: cycloid-local-tls
      hosts:
      - console.cycloid.local

backend:
  ingress:
    enabled: true
    hosts:
      - host: api.cycloid.local
        paths:
          - path: /
            pathType: ImplementationSpecific
    tls:
    - secretName: cycloid-local-tls
      hosts:
      - api.cycloid.local
```


---

# Enable the Cloud Cost Management feature

Important

This Elasticsearch endpoint needs to respect the following requirements:

* Version: up to 8.19.x
* Plugins: mapper-murmur3

Ensure the following configuration is set:

elasticsearch.yml

```
action.destructive_requires_name: false
```

## Using an external Elasticsearch[​](#using-an-external-elasticsearch "Direct link to Using an external Elasticsearch")

In order to use Cycloid Cloud Cost Management capabilities, you will need give the Cycloid Console access to an existing Elasticsearch node/cluster.

* Cycloid Self-Hosted Instances
* Cycloid Self-Hosted Kubernetes

To enable it, the configuration is done with variables set in `environments/cycloid.yml`

Example:

environments/cycloid.yml

```
###########################
# Cost Explorer / Cloud Cost Management feature (api params)
###########################
cost_explorer_es_url: "https://elasticsearch_url:9200"
cost_explorer_es_username: "elastic"
cost_explorer_es_password: "password"
cost_explorer_es_insecure_skip_tls: true # ignore certificate errors if there are any
```

To enable it, search for the `externalElasticsearch` section in your `values.custom.yaml`, switch the `enabled` field to `true` and fill out the remaining fields with the information that will be used by the Cycloid Backend to connect to your ElasticSearch endpoint and make sure it will be capable to access it.

You can connect the Cycloid Console to this Elasticsearch cluster using, for e.g., the following `values.custom.yaml` Helm chart configuration:

```
…
#
# External Elasticsearch Configuration
#
externalElasticsearch:
  # for now, the externalElasticsearch config will be at first
  # the only solution to configure the backend for Cloud Cost Management
  enabled: true
  #External ES server protocol
  scheme: https
  #External ES server host
  host: cost-explorer-es-http
  #External ES server port
  port: 9200
  #External ES server database
  username: elastic
  #External ES password
  password: ""
  #The name of an existing secret with database credentials
  # NOTE: Must contain key `elasticsearch-password` by default is not overriden with `existingSecretKey`
  # NOTE: When it's set, the `externalElasticsearch.password` parameter is ignored
  existingSecret: cost-explorer-es-elastic-user
  existingSecretKey: elastic
…
```

If you are using an Elasticsearch endpoint over HTTPS with custom certificates, you will need to either tell the Cycloid Backend to ignore Insecure TLS warnings with the following environment variable:

```
…
backend:
  …
  extraEnvVars:
    COST_EXPLORER_ES_INSECURE_SKIP_TLS: true
…
```

or give it access to the Elasticsearch CA certificate through a Kubernetes secret with:

```
…
backend:
  …
  extraSecretEnvVars:
    - envName: COST_EXPLORER_ES_CA_CERT
      secretName: cost-explorer-es-http-certs-public
      secretKey: ca.crt
…
```

Don't forget to upgrade your Helm release to take your changes into account:

* Kubernetes
* Openshift

```
helm upgrade -n ${NAMESPACE} --values values.custom.yaml cycloid .
```

```
helm upgrade -n ${NAMESPACE} --values values.custom.yaml --values values.openshift.custom.yaml cycloid .
```

## Using a local Elasticsearch (docker)[​](#using-a-local-elasticsearch-docker "Direct link to Using a local Elasticsearch (docker)")

* Cycloid Self-Hosted Instances
* Cycloid Self-Hosted Kubernetes

We can provide a default [Elasticsearch](https://hub.docker.com/_/elasticsearch) in order to be used out-of-the-box with Cycloid. Obviously, it does not replace a fully configured cluster but you can use it a solid base for your PoC / dev tests. It can be configured through this variables:

To enable it, the configuration is done with variables set in `environments/cycloid.yml`

warning

If you want to use the local elasticsearch, make sure there is `elasticsearch` define in your **inventory** file

```
# default user is "elastic"
cycloid_elasticsearch_password: "$(< /dev/urandom tr -dc _A-Z-a-z-0-9 | head -c32)"
```

A recommended way to deploy a ElasticSearch cluster in Kubernetes is to use the official [Elastic ECK Operator](https://www.elastic.co/fr/elastic-cloud-kubernetes), which can be deployed following [their documentation](https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-deploy-eck.html).

The Elastic ECK Operator gives you the ability to deploy complex and full-featured Elasticsearch cluster scenarios using their custom kubernetes resource called `Elasticsearch`. Here a very small and simple single instance Elasticsearch Kubernetes manifest, but this is merely an example for the purpose of that guide and shouldn't be taken as is. Your [Elasticsearch deployment](https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-elasticsearch-specification.html) scenario needs to be evaluated depending on how much data you are planning to ingest.

```
apiVersion: elasticsearch.k8s.elastic.co/v1
kind: Elasticsearch
metadata:
  name: cost-explorer
  labels:
    app.kubernetes.io/name: cost-explorer
spec:
  version: 8.19.4
  nodeSets:
  - name: hot
    count: 1
    config:
      node.roles: [ data, ingest, master ]
      action.destructive_requires_name: false
    podTemplate:
      spec:
        initContainers:
        - name: install-plugins
          command: ['sh', '-c', 'bin/elasticsearch-plugin install mapper-murmur3']
        - name: sysctl
          securityContext:
            privileged: true
            runAsUser: 0
          command: ['sh', '-c', 'sysctl -w vm.max_map_count=262144']
        containers:
        - name: elasticsearch
          resources:
            requests:
              memory: 2Gi
            limits:
              memory: 4Gi
    volumeClaimTemplates:
    - metadata:
        name: elasticsearch-data # Do not change this name unless you set up a volume mount for the data path.
      spec:
        accessModes:
        - ReadWriteOnce
        resources:
          requests:
            storage: 10Gi
```

Then, ensure to configure `externalElasticsearch` in your `values.custom.yaml` Helm chart configuration.


---

# Enable the Cost Estimation feature

To enable [cost-estimation](/reference/cost-estimation/.md), Cloud provider price need to be injested regularly.

Cronjob can be enabled per cloud-provider to injest price with the following variables:

* Cycloid Self-Hosted Instances
* Cycloid Self-Hosted Kubernetes

environments/cycloid.yml

```
#############################
# Cost Estimation injestion #
#############################
cycloid_job_cost_estimation_injection_aws: true
cycloid_job_cost_estimation_injection_azure: true

# can't enable gcp import without a valid gcp cred json
# To enable gcp ingestion, a gcp json credential need to be provided with
# cost_estimation_gcp_cred_json: "{....}"
# cost_estimation_gcp_project: "gcp_project_name"
# cycloid_job_cost_estimation_injection_gcp: true

# Default Every sunday
# cost_estimation_ingestion_schedule: "Sun *-*-* 00:00:00"
```

Service can be started to **force** an ingestion

```
systemctl start cycloid-job-cost-estimation-ingestion_container.service
```

To automate price ingestion, you can enable a Kubernetes CronJob.

**AWS** prices ingestion:

```
backend:
  cronJob:
    costEstimation:
      aws:
        enabled: true
        schedule: "0 0 * * 0"
```

**Azure** prices ingestion:

```
backend:
  cronJob:
    costEstimation:
      azure:
        enabled: true
        schedule: "0 0 * * 0"
```

**GCP** prices ingestion:

The GCP Pricing API requires authentication. You can use a Kubernetes secret to provide GCP credentials to the ingestion job. First, obtain your `gcp-credentials.json` file and create the secret as follows:

```
kubectl create secret generic pricing-ingest-google-credential --from-file=gcp-credentials.json
```

Then enable GCP price ingestion:

```
backend:
  cronJob:
    costEstimation:
      gcp:
        enabled: false
        schedule: "0 0 * * 0"
        secretName: pricing-ingest-google-credential
```


---

# MinIO

[MinIO](https://min.io/) is a high-performance, S3 compatible object store. It is built for large scale AI/ML, data lake and database workloads.

## Installation[​](#installation "Direct link to Installation")

* Cycloid Self-Hosted Instances
* Cycloid Self-Hosted Kubernetes

[MinIO Docker](https://min.io/docs/minio/container/index.html) version is used.

Add a `minio` group to your Ansible inventory to specify the server on which it will be installed.

inventory

```
[minio:children]
cycloid
```

Set the [root user](https://min.io/docs/minio/container/administration/identity-access-management/minio-user-management.html#minio-users-root) with access to all actions and resources on the deployment

environments/cycloid.yml

```
minio_root_user: AKIEXAMPLE
minio_root_password: EXAMPLEKEY

# Enable/Disable MinIo console on port 9001
minio_browser: off
```

Please follow the [Single-Node Single-Drive MinIO server onto Kubernetes](https://min.io/docs/minio/kubernetes/upstream/index.html?ref=docs-redirect#) for early **development and evaluation** of MinIO Object Storage and its S3-compatible API layer.

Alternatively use the [MinIO Operator](https://min.io/docs/minio/kubernetes/upstream/operations/installation.html#minio-operator-installation) to deploy and manage **production-ready** MinIO tenants on Kubernetes.

**AWS CLI** is a unified tool to manage AWS services. It is frequently the tool used to transfer data in and out of AWS S3. It works with any S3 compatible cloud storage service. Check out the [documentation](https://min.io/docs/minio/linux/integrations/aws-cli-with-minio.html) to learn how to configure and use AWS CLI to manage data with MinIO Server.


---

# Monitoring

## Services and Cycloid API Health metrics[​](#services-and-cycloid-api-health-metrics "Direct link to Services and Cycloid API Health metrics")

To monitor the status of Cycloid services and the API itself, a dedicated health endpoint is available at:

```
https://<api-url>/health_check
```

This endpoint provides service health information in Prometheus-compatible format, allowing seamless integration with monitoring and alerting systems such as Prometheus, Grafana, or Alertmanager.

Each exposed metric represents the health status of an individual service. The metric values are defined as follows:

* `1` the service is healthy
* `0` the service is unhealthy

The `/health_check` endpoint can be used to verify that the API itself is running. When the API is operational, this endpoint will always return an **HTTP 200 OK** status.

### Example Output[​](#example-output "Direct link to Example Output")

Below is an example response from the `/health_check` endpoint:

```
# HELP health_status_concourse The health status of the service concourse (1 for healthy, 0 for unhealthy)
# TYPE health_status_concourse gauge
health_status_concourse 1

# HELP health_status_elasticsearch The health status of the service elasticsearch (1 for healthy, 0 for unhealthy)
# TYPE health_status_elasticsearch gauge
health_status_elasticsearch 1

# HELP health_status_email The health status of the service email (1 for healthy, 0 for unhealthy)
# TYPE health_status_email gauge
health_status_email 1

# HELP health_status_mysql The health status of the service mysql (1 for healthy, 0 for unhealthy)
# TYPE health_status_mysql gauge
health_status_mysql 1

# HELP health_status_redis The health status of the service redis (1 for healthy, 0 for unhealthy)
# TYPE health_status_redis gauge
health_status_redis 1

# HELP health_status_redis_worker The health status of the service redis_worker (1 for healthy, 0 for unhealthy)
# TYPE health_status_redis_worker gauge
health_status_redis_worker 1

# HELP health_status_vault The health status of the service vault (1 for healthy, 0 for unhealthy)
# TYPE health_status_vault gauge
health_status_vault 1
```

### Integration Tips[​](#integration-tips "Direct link to Integration Tips")

* The `/health_check` endpoint can be scraped directly by Prometheus for continuous monitoring.
* You can create alerting rules based on the metric values (e.g., trigger an alert if any `health_status_*` metric equals `0`).
* For debugging, the endpoint can also be accessed manually via curl or a web browser.

```
curl -s https://<api-url>/health_check
```

## Self-Hosted Instances metrics[​](#self-hosted-instances-metrics "Direct link to Self-Hosted Instances metrics")

The [Node Exporter](https://github.com/prometheus/node_exporter?tab=readme-ov-file#enabled-by-default) is a lightweight Prometheus exporter used to collect host-level system metrics. It provides detailed visibility into hardware and operating system performance, allowing Prometheus to monitor cpu, mem, disk ... over time.

Node Exporter can be managed through the Ansible role `prometheus.prometheus.node_exporter` by setting the following Ansible variable:

```
enable_monitoring: true
```

Once installed, Node Exporter exposes its metrics on port `9100`. Prometheus can then scrape these metrics from each host at the `/metrics` endpoint (e.g., `http://<hostname>:9100/metrics`).


---

# Redis

## TLS with external Redis[​](#tls-with-external-redis "Direct link to TLS with external Redis")

* Cycloid Self-Hosted Instances
* Cycloid Self-Hosted Kubernetes

If your external Redis uses a self-signed certificate or you want to disable the hostname verification, you can set `cycloid_cache_insecure_skip_tls` to `true`. This will allow the connection to Redis to happen even if the certificate is not trusted or the hostnames do not match.

environments/cycloid.yml

```
# Allow insecure TLS/SSL with Redis. Usefull when using local redis with selfsigned certs
cycloid_cache_insecure_skip_tls: true
```

Or to improve the security, you can provide your CA certificate to the Cycloid API during the installation. To do so, place the redis CA certificate in the `datas/ssl/cycloid-redis.crt` and run ansible.

Enable Redis TLS connection by setting

values.custom.yaml

```
externalRedis:
  tls:
    enabled: true
```

If your external Redis uses a self-signed certificate or you want to disable the hostname verification, you can set `REDIS_INSECURE_SKIP_TLS` to `true`. This will allow the connection to Redis to happen even if the certificate is not trusted or the hostnames do not match.

values.custom.yaml

```
externalRedis:
  tls:
    enabled: false

backend:
  extraEnvVars:
    REDIS_INSECURE_SKIP_TLS: true
```

Or to improve the security, you can provide your CA certificate to the Cycloid API during the installation. To do so, define the `REDIS_CA_CERT`environment variable.

You can create a kubernetes secret containing the CA certificate

```
kubectl create secret generic cycloid-redis-crt \
  --from-file=ca.crt=/path/to/ca.crt
```

And provide it to Cycloid API

values.custom.yaml

```
backend:
  extraSecretEnvVars:
    - envName: REDIS_CA_CERT
      secretName: cycloid-redis-crt
      secretKey: ca.crt
```


---

# SMTP configuration

Cycloid require a SMTP server to send email for invitation/notification.

## Externam SMTP server[​](#externam-smtp-server "Direct link to Externam SMTP server")

* Cycloid Self-Hosted Instances
* Cycloid Self-Hosted Kubernetes

The configuration is done with variables set in `environments/cycloid.yml`

Caution

If you want to use an external SMTP server, make sure there is no `smtp_server` define in your **inventory** file

Example:

environments/cycloid.yml

```
cycloid_email_smtp_svr_addr: "smtp.gmail.com:587"
cycloid_email_smtp_username: mynotification@gmail.com
cycloid_email_smtp_password: examplepassword
cycloid_email_addr_from: "Cycloid Console <noreply@domain.tld>"
cycloid_email_addr_return_path: bounce@cycloid.io

# Allow insecure TLS/SSL with email or un-authentified SMTP access
cycloid_email_skip_tls_check: false
```

The following variables are available to configure your SMTP server:

* **cycloid\_email\_smtp\_svr\_addr**: Domain and port to reach your SMTP server
* **cycloid\_email\_smtp\_username**: Username if authentication is required or let it empty
* **cycloid\_email\_smtp\_password**: Password if authentication is required or let it empty
* **cycloid\_email\_addr\_from**: Email address shown as FROM
* **cycloid\_email\_addr\_return\_path**: Email address used to process the bounces that occur in your emails
* **cycloid\_email\_skip\_tls\_check**: Allow insecure TLS/SSL with email. Usefull when using local postfix as relayhost with selfsigned certs

The configuration is done with variables set in `values.custom.yaml` under `backend.extraEnvVars`.

```
backend:
  extraEnvVars:
    EMAIL_SMTP_SVR_ADDR: "smtp.gmail.com:587"
    EMAIL_SMTP_USERNAME: "mynotification@gmail.com"
    EMAIL_SMTP_PASSWORD: "examplepassword"
    EMAIL_ADDR_FROM: "Cycloid Console <noreply@domain.tld>"
    EMAIL_ADDR_RETURN_PATH: "bounce@cycloid.io"
    # Allow insecure TLS/SSL with email or un-authentified SMTP access
    EMAIL_SKIP_TLS_CHECK: false
```

The following variables are available to configure your SMTP server:

* **EMAIL\_SMTP\_SVR\_ADDR**: Domain and port to reach your SMTP server
* **EMAIL\_SMTP\_USERNAME**: Username if authentication is required or let it empty
* **EMAIL\_SMTP\_PASSWORD**: Password if authentication is required or let it empty
* **EMAIL\_ADDR\_FROM**: Email address shown as FROM
* **EMAIL\_ADDR\_RETURN\_PATH**: Email address used to process the bounces that occur in your emails
* **EMAIL\_SKIP\_TLS\_CHECK**: Allow insecure TLS/SSL with email. Usefull when using local postfix as relayhost with selfsigned certs

## Fake SMTP Server (For Testing and Debugging Purposes Only)[​](#fake-smtp-server-for-testing-and-debugging-purposes-only "Direct link to Fake SMTP Server (For Testing and Debugging Purposes Only)")

Currently, the Cycloid API requires an SMTP server to operate. This requirement is expected to be removed in the future. In the meantime, a fake SMTP server can be deployed for testing purposes.

* Cycloid Self-Hosted Instances
* Cycloid Self-Hosted Kubernetes

By default, self-hosted instances are configured to deploy a fake SMTP server through the Ansible inventory file. Here's how to enable the fake SMTP server:

inventory

```
[cycloid]
1.2.3.4

[smtp_server:children]
cycloid
```

Please follow this manual update process.

Install [MailHog](https://github.com/codecentric/helm-charts/tree/master/charts/mailhog)

* Kubernetes
* Openshift

```
helm repo add codecentric https://codecentric.github.io/helm-charts
helm -n ${NAMESPACE} install mailhog codecentric/mailhog
```

```
helm repo add codecentric https://codecentric.github.io/helm-charts
helm -n ${NAMESPACE} install mailhog codecentric/mailhog --set securityContext=null
```

Make sure the 2 following variables are properly set under `backend.extraEnvVars` in your `values.custom.yaml`

```
    EMAIL_SMTP_SVR_ADDR: "mailhog:1025"
    EMAIL_DEV_MODE: true
```

MailHog will act as a fake smtp server, that means you will not receive cycloid signup confirmation email. So when a user signup, to force users validation, please run the following script:

```
./scripts/mysql-force-user-email-validation.sh
```


---

# Advanced Configurations Unreferenced

## Workers[​](#workers "Direct link to Workers")

### Contact local service installed on the worker from a container[​](#contact-local-service-installed-on-the-worker-from-a-container "Direct link to Contact local service installed on the worker from a container")

Although it is not recommended, there are some use cases (primarily for Proof of Concept (PoC) scenarios) where you might need your worker to access local services, such as a local DNS server or a local Docker registry.

To enable containers to access host services, simply add the following **Worker** **environment variables**:

```
  CONCOURSE_GARDEN_ALLOW_HOST_ACCESS: true
  CONCOURSE_GARDEN_DESTROY_CONTAINERS_ON_STARTUP: true
```

During a Proof of Concept (PoC), we recommend setting `CONCOURSE_GARDEN_DESTROY_CONTAINERS_ON_STARTUP` to ensure that all containers are recreated and the `ALLOW_HOST_ACCESS` mode is applied universally right after the worker restarts.

Note

if you want to use dnsmasq to expand `/etc/hosts` to your pipelines, please refer to the section on [custom DNS hosts](#how-to-share-custom-dns-hosts-entries-with-my-containers) section

## How to share custom dns hosts entries with my containers[​](#how-to-share-custom-dns-hosts-entries-with-my-containers "Direct link to How to share custom dns hosts entries with my containers")

* Cycloid Self-Hosted Instances

For testing or development, entries in `/etc/hosts` combined with `Dnsmasq` could be used as a nameserver in your containers.

caution

We highly recommend using your own DNS servers for internal domains with production.

**Dnsmasq** is a lightweight, easy to configure DNS forwarder, designed to provide DNS services to a small-scale network. It can serve the names of local machines which are not in the global DNS. It will be used to share your `/etc/hosts` with containers.

To install it manually on your on-prem server, please run

```
apt-get install dnsmasq
```

Configure your Dnsmasq to read `/etc/hosts`

```
vim /etc/dnsmasq.conf
expand-hosts
interface=*
```

Don't forget to reload

```
systemctl reload dnsmasq
```

Your **Dnsmasq** is now ready. The last step set your on-prem server as DNS for your containers. Private IP or docker bridge IP can be used. Please define the following variable in `environments/cycloid.yml` and run the install playbook.

```
container_args_extra: "--dns 172.17.0.1"
```

## Using custom Certificates Authority (CA) **Cycloid Self-Hosted Instances**[​](#using-custom-certificates-authority-ca-cycloid-self-hosted-instances "Direct link to using-custom-certificates-authority-ca-cycloid-self-hosted-instances")

### Deploy custom Certificates Authority on servers and workers[​](#deploy-custom-certificates-authority-on-servers-and-workers "Direct link to Deploy custom Certificates Authority on servers and workers")

You can install your own Certificate Authority certificate on your on-premises servers with the Ansible playbook. To do so, place your `CA` cert under `datas/rootca/` (default value of `ca_certificates_local_path`)

Example:

```
ls datas/rootca/
CybertrustGlobalRoot.crt  DigiCertHighAssuranceEVRootCA.crt  DigiCertSHA2HighAssuranceServerCA.crt
```

Then run the playbook.

### Deploy custom Certificates Authority on containers (Cycloid API)[​](#deploy-custom-certificates-authority-on-containers-cycloid-api "Direct link to Deploy custom Certificates Authority on containers (Cycloid API)")

Your Certificate Authority certificate on your servers can be shared with the Cycloid API container.

To do so, set the `ca_certificates_container_shared: true` Ansible variable in your `environments/cycloid.yml` file.

Note

Another solution would be to build your own Cycloid API docker image with your included CA, e.g.

```
FROM 661913936052.dkr.ecr.eu-west-1.amazonaws.com/youdeploy-http-api:prod
COPY ca.crt /usr/local/share/ca-certificates/
RUN update-ca-certificates
```

### Using custom Certificates Authority (CA) into my pipelines (Worker)[​](#using-custom-certificates-authority-ca-into-my-pipelines-worker "Direct link to Using custom Certificates Authority (CA) into my pipelines (Worker)")

If you want to integrate your own CA certificate in your pipelines, there is one thing to have in mind.

Pipelines are composed of 2 "containers" components:

* **Resources**: They are used in your pipeline job steps with `put` or `get`.
* **Tasks**: They are present in your job steps with `task` keyword.

**1. Resources**: Concourse Currently offer a global way to forward the CA certificates from your worker host to **resources** since the [version 3.9.0](https://github.com/concourse/concourse/releases/tag/v3.9.0). You can read more about it in [Concourse doc](https://concourse-ci.org/implementing-resource-types.html#resource-certs) or the dedicated [github issue](https://github.com/concourse/concourse/issues/1027).

To enable it, edit your `environments/cycloid.yml` and add `ca_certificates_container_shared: true`.

Note

Or manually set concourse\_worker\_env

environments/cycloid.yml

```
concourse_worker_env:
  # like /etc/ssl/certs or /etc/pki/tls/certs depending on your Linux distribution.
  CONCOURSE_CERTS_DIR=/etc/ssl/certs/
```

**2. Tasks**: As seen above Concourse only offers a certificates forwarding to resources. For the `task` you need to inject your own certificate inside the docker image you are using. This could be done using `Cycloid credentials` during the pipeline runtime or directly injected to your docker image.

For example let's do it in our cycloid-toolkit image based on alpine linux, simply create a `Dockerfile` with the following content:

```
FROM cycloid/cycloid-toolkit:latest
COPY ca.crt /usr/local/share/ca-certificates/mycert.crt
RUN update-ca-certificates
```

Then build and push your image:

```
docker build -t myuser/my-cycloid-toolkit:latest .
docker push myuser/my-cycloid-toolkit:latest
```

Then you should be able to use your own `myuser/my-cycloid-toolkit` image containing the CA certificate.


---

# Vault

## MySQL storage backend[​](#mysql-storage-backend "Direct link to MySQL storage backend")

The [MySQL storage backend](https://developer.hashicorp.com/vault/docs/configuration/storage/mysql) is used to persist Vault's data in a MySQL server or cluster.

* Cycloid Self-Hosted Instances
* Cycloid Self-Hosted Kubernetes

Override the `vault_config` to define your storage configuration (such as MySQL).

environments/cycloid.yml

```
vault_config:
  storage:
    mysql:
      address: "{{ cycloid_db_host }}:{{ cycloid_db_port }}"
      username: "{{ cycloid_db_user }}"
      password: "{{ cycloid_db_password }}"
      database: "vault"
  ui: true
  listener:
    tcp:
      address: "0.0.0.0:8200"
      tls_disable: "0"
      tls_cert_file: "/vault/config/ssl.crt"
      tls_key_file:  "/vault/config/ssl.key"
  default_lease_ttl: "168h"
  max_lease_ttl: "720h"
```

[Create a secret](https://developer.hashicorp.com/vault/docs/platform/k8s/helm/run#protecting-sensitive-vault-configurations) containing your storage configuration to protect sensitive information.

```
cat <<EOF >>config.hcl
storage "mysql" {
  address = "mysql-host"
  username = "mysql-user"
  password = "mysql-password"
  database = "mysql-db-name"
}
EOF

kubectl create secret generic vault-storage-config --from-file=config.hcl
```

From the `values.custom.yaml` under the **vault section**, ensure to disable local `dataStorage`. Mount your `config.hcl` as a secret and reference it using `extraArgs`.

values.custom.yaml

```
vault:
  server:
    dataStorage:
      enabled: false

    # mount the storage configuration
    volumes:
      - name: userconfig-vault-storage-config
        secret:
          secretName: vault-storage-config
          defaultMode: 420
    volumeMounts:
      - name: userconfig-vault-storage-config
        mountPath: "/vault/userconfig/vault-storage-config"
        readOnly: true
    extraArgs: "-config=/vault/userconfig/vault-storage-config/config.hcl"
```

## Auto Unseal configuration[​](#auto-unseal-configuration "Direct link to Auto Unseal configuration")

Vault has to be [unsealed](https://developer.hashicorp.com/vault/docs/configuration/seal) anytime it start. If you need to automate it, you can configure auto-unsealing.

Vault supports opt-in automatic unsealing via cloud technologies: AliCloud KMS, [AWS KMS](https://developer.hashicorp.com/vault/tutorials/auto-unseal/autounseal-aws-kms), [Azure Key Vault](https://developer.hashicorp.com/vault/tutorials/auto-unseal/autounseal-azure-keyvault), [Google Cloud KMS](https://developer.hashicorp.com/vault/tutorials/auto-unseal/autounseal-gcp-kms), and OCI KMS. This feature enables operators to delegate the unsealing process to trusted cloud providers to ease operations in the event of partial failure and to aid in the creation of new or ephemeral clusters.

If Auto-unsealing is required, we highly recommend utilizing one of the supported options mentioned.

* Cycloid Self-Hosted Instances
* Cycloid Self-Hosted Kubernetes

However, a straightforward solution is enabled by default with the following configuration:

environments/cycloid.yml

```
vault_auto_unseal: true
```

This configuration enables Vault to automatically unseal itself at startup by utilizing the unseal keys stored on the instance.

However, for a more straightforward solution, the following custom configuration can be employed.

After initializing Vault, generate a Kubernetes secret containing the Vault unseal keys:

```
cd /opt/cycloid
cat scripts/.out/vault-init.json | jq -r  .unseal_keys_b64[] > /tmp/unseal_keys
kubectl -n $NAMESPACE create secret generic vault-unseal-keys --from-file=/tmp/unseal_keys
rm /tmp/unseal_keys
```

Update the `vault:` section from `values.custom.yaml` to mount the `vault-unseal-keys` secret and run `vault operator unseal` as `postStart` command.

values.custom.yaml

```
vault:
  server:
    postStart:
      - /bin/sh
      - -c
      - for i in $(cat /opt/vault-unseal-keys/unseal_keys);do vault operator unseal $i;done
    volumes:
      - name: vault-unseal-keys
        secret:
          secretName: vault-unseal-keys
    volumeMounts:
      - mountPath: /opt/vault-unseal-keys
        name: vault-unseal-keys
        readOnly: true
```

This configuration enables Vault to automatically unseal itself at startup by utilizing the unseal keys stored as Kubernetes secrets.


---

# Demo - POC Self-Hosted platform

danger

This section describes Self-Hosted platforms for **evaluation, training or test purposes ONLY**.

/!\ DO NOT USE this guide for production setup.

For Self-Hosted production deployments, an architecture review must be done with Cycloid team to review your specific environment and requirements.

For evaluationn, we offer two ways to deploy your Self-Hosted Cycloid Platform:

* On [**Compute Instances**](/cookbook/dedicated-platform/demo-poc/instances.md) such as EC2, Azure VMs, GCP compute VMs, VMware VMs, etc.
* On a [**Kubernetes cluster**](/cookbook/dedicated-platform/demo-poc/kubernetes.md) such as EKS, AKS, GKE or any self-managed Kubernetes cluster.

## Prerequisites[​](#prerequisites "Direct link to Prerequisites")

* Cycloid provided the **credentials** to access our Container Registry.
* Cycloid provided the **license key** to activate the platform once it is installed.


---

# Deploy on instances

## Solution Description[​](#solution-description "Direct link to Solution Description")

This section describes how to deploy the Cycloid platform as well as one worker on a single compute instance running on your public or private cloud provider.

Caution!

**Do not use this guide for production deployments**. This simple one instance deployment shall be used only for evaluation, training or test purposes.

The use cases should also require limited processing power (such as infrastructure and application deployments using Terraform, Ansible or Helm).

Full installation documentation is available in the [reference documentation](/reference.md).

### Architecture Diagram[​](#architecture-diagram "Direct link to Architecture Diagram")

Here is an architecture diagram of the components running on the single compute instance:

![](/img/cookbook/instance_archi.png)

Caution!

The installation of Minio (S3-like cloud storage) and Elasticsearch (required for finOps & GreenOps module) are not covered here.

### Instance Requirements[​](#instance-requirements "Direct link to Instance Requirements")

The Cycloid single instance server:

* shall have a minimum size of **4 CPU / 8GB RAM / 100GB SSD**
* shall run under **Debian 12**
* shall allow for 80/TCP and 443/TCP\*\* ingress connectivity
* shall allow for **terminal connectivity** (via SSH or others).

### Network Architecture[​](#network-architecture "Direct link to Network Architecture")

After a default run of this playbook on a server, you will find those different services :

| Source                        | Destination                          | Destination Port | Comment                                                                          |
| ----------------------------- | ------------------------------------ | ---------------- | -------------------------------------------------------------------------------- |
| All                           | Cycloid VM (frontend)                | 80/TCP 443/TCP   | **Required** - Access to Cycloid Console from workstations                       |
| All                           | Cycloid VM (backend)                 | 80/TCP 443/TCP   | **Required** - Access to Cycloid API from workstations                           |
| Cycloid VM (worker)           | Cycloid Public Docker Registry       | 443/TCP          | **Required** - Get container images from internet to run pipeline jobs.          |
| Cycloid VM (worker)           | Your Container Registry              | 443/TCP          | Optional - Get container images from your private registry to run pipeline jobs. |
| Cycloid VM (backend & worker) | Your Git Repository                  | 22/TCP 443/TCP   | **Required** - Get stacks and config using SSH ot HTTP auth.                     |
| Cycloid VM (backend & worker) | Your Cloud Storage for TFState files | 443/TCP          | **Required if using Terraform** - Get Terraform state files.                     |
| Cycloid VM (backend & worker) | Cycloid Git Repository               | 22/TCP 443/TCP   | Optional - Get community stacks.                                                 |

Here is a high-level diagram of the network architecture:

![](/img/cookbook/self-hosted-architecture.png)

### DNS Records[​](#dns-records "Direct link to DNS Records")

You will also need **a DNS record** pointing to your Cycloid deployment. The client workstations will use this domain name to access the Cycloid Console and API.

## Install Cycloid Platform[​](#install-cycloid-platform "Direct link to Install Cycloid Platform")

The first step will be to create your Cycloid instance according to the requirements listed in the [Instance Requirements](#instance-requirements) section.

Configure your DNS record pointing at the Cycloid single instance. You could use domains something such as `console-cycloid.yourdomain.com`.

Connect to your instance (the default user on Debian is `admin`) and download `cycloid-onprem.tar` archive from the URL provided by Cycloid.

```
wget https://cycloid-onprem-archives.s3.eu-west-1.amazonaws.com/<RandomString>/cycloid-onprem.tar
tar xf cycloid-onprem.tar
cd cycloid-onprem
```

Next, configure the domain name you created to access the Cycloid console (for example `console-cycloid.yourdomain.com`):

```
export CYCLOID_CONSOLE_DNS=<your_console_url>
```

Run the installation:

```
sudo -E bash helper.sh install
```

You can now connect to Cycloid console using the username and password provided in the script output in your console.

### Other options[​](#other-options "Direct link to Other options")

```
bash helper.sh help

options:
  install              Install requirements, Cycloid and pipeline worker.
  install-cycloid      Install Cycloid only.
  install-worker       Install pipeline worker only.
  reinstall-cycloid    Reinstall Cycloid.
  uninstall            Uninstall Cycloid.
  report               Generate a report to share with Cycloid team.
```

## Troubleshooting[​](#troubleshooting "Direct link to Troubleshooting")

### Helper logs[​](#helper-logs "Direct link to Helper logs")

Where to find the script logs?

```
cat /tmp/cycloid-install.log
```

### Report[​](#report "Direct link to Report")

Create a report to help Cycloid troubleshoot an issue:

```
bash helper.sh report
```


---

# Deploy on Kubernetes

## Solution Description[​](#solution-description "Direct link to Solution Description")

This section describes how to quickly install a Kubernetes cluster that meets the Cycloid requirements as well as the Cycloid platform itself running as a Kubernetes workload.

Caution!

**Do not use this guide for production deployments**. This simple deployment shall be used only for evaluation, training or test purposes.

Full installation documentation is available in the [reference documentation](/reference.md).

### Architecture Diagram[​](#architecture-diagram "Direct link to Architecture Diagram")

Here is an architecture diagram of the deployment covered by this guide:

![](/img/cookbook/k8s_archi.png)

### Kubernetes Cluster Dimensioning[​](#kubernetes-cluster-dimensioning "Direct link to Kubernetes Cluster Dimensioning")

To run Cycloid platform as well as one worker for evaluation purposes with use cases requiring limited processing power (such as infrastructure and application deployments using Terraform, Ansible or Helm), you will need a cluster size of **4 CPU / 8GB RAM / 100GB SSD**. You could break down the cluster node sizing into 2 nodes of 2 CPU / 4 GB RAM / 50GB SSD.

Caution!

If you intend to use Cycloid Cloud Cost Management, you will need to install an external Elasticsearch that is not included in this dimensioning.

Please read the [FAQ](#frequenly-asked-questions) section below in this case.

### Network Architecture[​](#network-architecture "Direct link to Network Architecture")

| Source              | Destination                          | Destination Port | Comment                                                                          |
| ------------------- | ------------------------------------ | ---------------- | -------------------------------------------------------------------------------- |
| All                 | Cycloid Frontend LoadBalancer        | 80/TCP 443/TCP   | **Required** - Access to Cycloid Console from workstations                       |
| All                 | Cycloid Backend LoadBalancer         | 80/TCP 443/TCP   | **Required** - Access to Cycloid API from workstations                           |
| Worker POD          | Cycloid Public Docker Registry       | 443/TCP          | **Required** - Get container images from internet to run pipeline jobs.          |
| Worker POD          | Your Container Registry              | 443/TCP          | Optional - Get container images from your private registry to run pipeline jobs. |
| Cycloid Backend POD | Your Git Repository                  | 22/TCP 443/TCP   | **Required** - Get stacks and config.                                            |
| Worker POD          | Your Git Repository                  | 22/TCP 443/TCP   | **Required** - Get stacks and config.                                            |
| Cycloid Backend POD | Your Cloud Storage for TFState files | 443/TCP          | Optional - Get Terraform state files.                                            |
| Worker POD          | Your Cloud Storage for TFState files | 443/TCP          | Optional - Get Terraform state files.                                            |
| Cycloid Backend POD | Cycloid Git Repository               | 22/TCP 443/TCP   | Optional - Get community stacks and config.                                      |
| Worker POD          | Cycloid Git Repository               | 22/TCP 443/TCP   | Optional - Get community stacks and config.                                      |

### DNS Records[​](#dns-records "Direct link to DNS Records")

You will need **two CNAME records** pointing to your Kubernetes cluster for the Console and API domains you intend to use.

## Install a Kubernetes Cluster[​](#install-a-kubernetes-cluster "Direct link to Install a Kubernetes Cluster")

### Prerequisites[​](#prerequisites "Direct link to Prerequisites")

Amazon Elastic Kubernetes Service (Amazon EKS) is a managed Kubernetes service to run Kubernetes in the AWS cloud and on-premises data centers. The Cycloid platform can be run as a workload on your EKS cluster.

To install and manage an EKS cluster, you will need to install and configure the following tools. Please follow the links to install each of them:

* `awscli` - The AWS Command Line Interface is a unified tool to manage your AWS services.<br /><!-- -->→ [Click here](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) to go to the installation procedure.

* `eksctl` – A command line tool for working with EKS clusters that automates many individual tasks.<br /><!-- -->→ [Click here](https://helm.sh/docs/intro/install/) to go to the installation procedure.

* `kubectl` – A command line tool for working with Kubernetes clusters.<br /><!-- -->→ [Click here](https://github.com/eksctl-io/eksctl/blob/main/README.md#installation) to go to the installation procedure.

* `aws-iam-authenticator` - A tool to use AWS IAM credentials to authenticate to a Kubernetes cluster. Amazon EKS uses IAM for user management and access to clusters. Out of the box, kubectl does not support IAM. To bridge the gap, you must install a binary on your system called  aws-iam-authenticator.<br /><!-- -->→ [Click here](https://docs.aws.amazon.com/eks/latest/userguide/install-aws-iam-authenticator.html) to go to the installation procedure.

tip

For MacOS, you can use the HomeBrew package manager to install these tools:

```
brew install awscli kubectl aws-iam-authenticator eksctl
```

### Checking User Permissions[​](#checking-user-permissions "Direct link to Checking User Permissions")

Kubernetes clusters managed by Amazon EKS make calls to other AWS services on your behalf to manage the resources that you use with the service. The IAM security principal that you're using must have permissions to create and describe an Amazon EKS cluster, to create an IAM role with the `AmazonEKSClusterPolicy` IAM policy and to work with related resources.

Make sure you are working with a user that meets the above requirements by running the following command:

```
aws sts get-caller-identity
```

### Create Cluster[​](#create-cluster "Direct link to Create Cluster")

Let's create a Kubernetes control plane with the `eksctl` tool. In the next command, please replace the placeholder with your preferred AWS region:

```
export EKS_CLUSTER_NAME=cycloid
export AWS_REGION=<your_region_code>
eksctl create cluster --name ${EKS_CLUSTER_NAME} --region ${AWS_REGION} --without-nodegroup
```

It should take at least 10 minutes, so please be patient.

Wait until the EKS cluster status is `ACTIVE`, then deploy some nodes:

```
eksctl create nodegroup --cluster ${EKS_CLUSTER_NAME} --region ${AWS_REGION} \
  --node-type t3a.medium --nodes 2 --nodes-min 2 --nodes-max 4
```

### Amazon EBS CSI plugin[​](#amazon-ebs-csi-plugin "Direct link to Amazon EBS CSI plugin")

We need the **Amazon EBS CSI plugin** which requires IAM permissions to make calls to AWS APIs on your behalf. To do that, first, allow the cluster to use AWS Identity and Access Management (IAM) for service accounts by running the following command:

```
eksctl utils associate-iam-oidc-provider --cluster ${EKS_CLUSTER_NAME} --region ${AWS_REGION} --approve
```

Then, create an Amazon EBS CSI plugin IAM role with `eksctl` with the following command:

```
eksctl create iamserviceaccount --cluster ${EKS_CLUSTER_NAME} --region ${AWS_REGION} \
    --name ebs-csi-controller-sa \
    --namespace kube-system \
    --role-name AmazonEKS_EBS_CSI_DriverRole \
    --role-only \
    --attach-policy-arn arn:aws:iam::aws:policy/service-role/AmazonEBSCSIDriverPolicy \
    --approve
```

Finally, add the Amazon EBS CSI add-on using `eksctl`:

```
eksctl create addon --name aws-ebs-csi-driver \
    --cluster ${EKS_CLUSTER_NAME} --region ${AWS_REGION} \
    --service-account-role-arn arn:aws:iam::$(aws sts get-caller-identity --query Account --output text):role/AmazonEKS_EBS_CSI_DriverRole \
    --force
```

#### Test Connectivity[​](#test-connectivity "Direct link to Test Connectivity")

Your `kubeconfig` file should have been updated automatically by `eksctl` tool with a new context for the created cluster. Make sure the connection to your new cluster is working with a `kubectl` command such as:

```
kubectl get nodes
```

**Congratulations!** You have now a fully functioning EKS cluster.

tip

If your `kubeconfig` file was not updated, you can do it by running this command:

```
aws eks update-kubeconfig --name ${EKS_CLUSTER_NAME} --region ${AWS_REGION}
```

When you are done with your Kubernetes cluster, you can destroy it with:

```
eksctl delete cluster --name ${EKS_CLUSTER_NAME} --region ${AWS_REGION}
```

## Install Cycloid Platform[​](#install-cycloid-platform "Direct link to Install Cycloid Platform")

### Prerequisites[​](#prerequisites-1 "Direct link to Prerequisites")

To install and manage your Cycloid deployment, you will need to install and configure the following tools. Please follow the links to install each of them:

* `awscli` - The AWS Command Line Interface is a unified tool to manage your AWS services to get Cycloid Helm chart and container images.
  <br />
  <!-- -->
  → [Click here](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) to go to the installation procedure.

- `kubectl` – A command line tool for working with Kubernetes clusters.<br /><!-- -->→ [Click here](https://github.com/eksctl-io/eksctl/blob/main/README.md#installation) to go to the installation procedure.

- `helm` - A command line tool for managing Charts. Charts are packages of pre-configured Kubernetes resources.<br /><!-- -->→ [Click here](https://kubernetes.io/docs/tasks/tools/) to go to the installation procedure.

- `helm S3 plugin` - A Helm plugin that provides Amazon S3 protocol support.<br /><!-- -->→ [Click here](https://github.com/hypnoglow/helm-s3) to go to the installation procedure.

- `jq` - A lightweight and flexible command-line JSON processor to make the Helm values configuration easy.<br /><!-- -->→ [Click here](https://jqlang.github.io/jq/download/) to go to the download page.

- `pwgen` - A command line tool to generate random passwords.<br /><!-- -->→ [Click here](https://www.scmgalaxy.com/tutorials/how-to-install-pwgen-in-linux-all-versions-and-mac-docker/) to get guidance on the installation options.

- `envsubst` - A command line tool to substitutes the values of environment variables.<br /><!-- -->→ [Click here](https://www.thegeekdiary.com/envsubst-command-not-found/) to get guidance on the installation options.

tip

For MacOS, you can use the HomeBrew package manager to install these tools. The installation of the prerequisites would be as simple as:

```
brew install awscli kubectl helm jq pwgen
helm plugin install https://github.com/hypnoglow/helm-s3.git
```

### Create a Cycloid Namespace[​](#create-a-cycloid-namespace "Direct link to Create a Cycloid Namespace")

Please make sure to create a Kubernetes NAMESPACE where Cycloid should be installed. We call it `cycloid` in this example, but you are free to choose another name:

```
export NAMESPACE=cycloid
kubectl create namespace ${NAMESPACE}
```

### Install ElasticSearch (optional)[​](#install-elasticsearch-optional "Direct link to Install ElasticSearch (optional)")

To use Cycloid Cloud Cost Management FinOps & GreenOps module, you will need to install an Elasticsearch cluster. **If you don't need Cycloid Cloud Cost Management, you can safely skip this section.**

Important

This Elasticsearch cluster needs to respect the following requirements:

* Version: up to 7.17.x
* Plugins: mapper-murmur3

The recommended way to deploy an ElasticSearch cluster in Kubernetes is to use the official [Elastic ECK Operator](https://www.elastic.co/fr/elastic-cloud-kubernetes), which can be deployed following [their documentation](https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-deploy-eck.html).

The Elastic ECK Operator gives you the ability to deploy complex and full-featured Elasticsearch cluster scenarios using their custom Kubernetes resource called `Elasticsearch`.

Once the Elastic ECK Operator is deployed, copy the following manifest in a file named `es.yaml`. This is a single instance of Elasticsearch Kubernetes manifest that could be used for evaluation purposes without much data. Configuration changes may be required depending on the foreseen volume of billing data ingested.

```
apiVersion: elasticsearch.k8s.elastic.co/v1
kind: Elasticsearch
metadata:
  name: cost-explorer
  labels:
    app.kubernetes.io/name: cost-explorer
spec:
  version: 7.17.1
  nodeSets:
  - name: hot
    count: 1
    config:
      node.roles: [ data, ingest, master ]
    podTemplate:
      spec:
        initContainers:
        - name: install-plugins
          command: ['sh', '-c', 'bin/elasticsearch-plugin install mapper-murmur3']
        - name: sysctl
          securityContext:
            privileged: true
            runAsUser: 0
          command: ['sh', '-c', 'sysctl -w vm.max_map_count=262144']
        containers:
        - name: elasticsearch
          resources:
            requests:
              memory: 2Gi
            limits:
              memory: 4Gi
    volumeClaimTemplates:
    - metadata:
        name: elasticsearch-data # Do not change this name unless you set up a volume mount for the data path.
      spec:
        accessModes:
        - ReadWriteOnce
        resources:
          requests:
            storage: 10Gi
```

Now, install your Elasticseach cluster like this:

```
kubectl apply -f es.yaml -n ${NAMESPACE}
```

### Renew the docker-registry token[​](#renew-the-docker-registry-token "Direct link to Renew the docker-registry token")

To access Cycloid docker images, a docker-registry token that expires is used. Cycloid Helm chart adds a Kubernetes cronjob to automatically renew the docker-registry token from Cycloid AWS credentials.

In order for the cronjob to work properly it's necessary to create a Kubernetes secret containing Cycloid AWS credentials. In the below command, make sure to **replace the placeholders with the Cycloid provided credentials**.

```
kubectl -n ${NAMESPACE} create secret generic cycloid-aws-creds \
    --from-literal=AWS_ACCESS_KEY_ID=<cycloid_aws_access_key_id> \
    --from-literal=AWS_SECRET_ACCESS_KEY=<cycloid_aws_secret_access_key>
```

tip

If you did not receive your Cycloid AWS credentials, please contact <support@cycloid.io>

#### NGINX Ingress Controller[​](#nginx-ingress-controller "Direct link to NGINX Ingress Controller")

We will use NGINX Ingress Controller to expose the Cycloid console and API externally to the EKS cluster. You can deploy it with the following command:

```
helm upgrade --install ingress-nginx ingress-nginx \
  --repo https://kubernetes.github.io/ingress-nginx \
  --namespace ${NAMESPACE}
```

### Set up AWS CLI Profile with Cycloid AWS Credentials[​](#set-up-aws-cli-profile-with-cycloid-aws-credentials "Direct link to Set up AWS CLI Profile with Cycloid AWS Credentials")

Configure a new AWS CLI profile with your Cycloid provided credentials:

```
export AWS_PROFILE=cycloid
aws configure --profile ${AWS_PROFILE}
```

if you are using an AWS EKS cluster

If you are using an EKS cluster, please make sure to use a named profile that is different than the default one, otherwise `kubectl` may not work anymore (`aws-iam-authenticator` requires owner access to your EKS Kubernetes cluster).

### Add the Cycloid Helm repository[​](#add-the-cycloid-helm-repository "Direct link to Add the Cycloid Helm repository")

Add the cycloid-onprem helm repository to helm locally:

```
helm repo add cycloid-onprem https://cycloid-onprem-helm-charts.s3.amazonaws.com/stable/cycloid/
```

Verify that helm can see the cycloid-onprem/cycloid chart

```
helm search repo cycloid-onprem/cycloid
```

### Hashicorp Vault Dependency Installation[​](#hashicorp-vault-dependency-installation "Direct link to Hashicorp Vault Dependency Installation")

To install the Hashicorp Vault dependency, the Cycloid Helm chart will need to be pulled locally (as opposed to installing it directly from the Helm repository). We will then ask you to make a copy of the default chart values to customize them.

First, pull the Helm chart:

```
helm pull --untar cycloid-onprem/cycloid
cd cycloid
```

if you want to pull a specific version

```
helm pull --untar cycloid-onprem/cycloid --version <version>
cd cycloid
```

We don't need to use Cycloid AWS credentials at this point so you can unset the Cycloid AWS CLI profile. This is especially important if you use an AWS EKS cluster via the `aws-iam-authenticator` tool:

```
unset AWS_PROFILE
```

Install the Hashicorp Vault dependency:

```
helm install -n ${NAMESPACE} \
    --values values.yaml \
    --set frontend.enabled=false \
    --set backend.enabled=false \
    --set mysql.enabled=false \
    --set redis.enabled=false \
    --set concourse.enabled=false \
    cycloid .
```

#### Vault Initialization[​](#vault-initialization "Direct link to Vault Initialization")

Let's initialize the Vault on your freshly installed platform:

```
bash scripts/vault-init.sh
```

Caution

Do not run `vault-init.sh` unless you want to install it from scratch. We highly recommend you make a backup of JSON files that have been generated in the `scripts/.out/` directory as they contain key information about Vault Unseal keys, initial root tokens and required Approle used by the Cycloid platform.

#### Vault Unsealing[​](#vault-unsealing "Direct link to Vault Unsealing")

You will need to enter 3 Vault Unseal Keys created in the initialization step and saved for your convenience in `scripts/.out/vault-init.json`.

If you have the `jq` utility installed locally, the values will be entered automatically.

```
bash scripts/vault-unseal.sh
```

#### Configuration[​](#configuration "Direct link to Configuration")

Next, you will need to enter the initial root token created in the initialization step and saved for your convenience in `scripts/.out/vault-init.json`.

If you have the `jq` utility installed locally, the values will be entered automatically.

```
bash scripts/vault-config.sh
```

### Helm Chart Configuration[​](#helm-chart-configuration "Direct link to Helm Chart Configuration")

#### Helm Chart Values Settings[​](#helm-chart-values-settings "Direct link to Helm Chart Values Settings")

We are going to customize the default Helm chart values by creating a `values.template.yaml` file with the following content:

```
frontend:
  url: "http://${CONSOLE_URL}"
  image:
    # Cycloid Console frontend version to use.
    tag: "latest-public"
  ingress:
    enabled: true
    className: "nginx"
    hosts:
      - host: ${CONSOLE_URL}
        paths:
          - path: /
            pathType: ImplementationSpecific
    tls: []
    #  - secretName: cycloid-local-tls
    #    hosts:
    #      - ${CONSOLE_URL}

backend:
  url: "http://${API_URL}"
  image:
    # Cycloid Console API version to use.
    tag: "latest-public"
  concourse:
    password: "${CONCOURSE_PWD}"
  vault:
    roleId: "${CYCLOID_VAULT_APPROLE_ROLE_ID}"
    secretId: "${CYCLOID_VAULT_APPROLE_SECRET_ID}"
  cryptoSigningKey: ${BACKEND_CRYPTO_SIGNING_KEY}
  extraEnvVars:
    EMAIL_SMTP_SVR_ADDR: "${SMTP_HOST}"
    EMAIL_SMTP_USERNAME: "${SMTP_USERNAME}"
    EMAIL_SMTP_PASSWORD: "${SMTP_PASSWORD}"
    EMAIL_DEV_MODE: ${EMAIL_DEV_MODE}
    COST_EXPLORER_ES_INSECURE_SKIP_TLS: true
  ingress:
    enabled: true
    className: "nginx"
    hosts:
      - host: ${API_URL}
        paths:
          - path: /
            pathType: ImplementationSpecific
    tls: []
    #  - secretName: cycloid-local-tls
    #    hosts:
    #      - ${API_URL}

## Use the MySQL chart dependency.
mysql:
  enabled: ${MYSQL_INSTALL}
  auth:
    rootPassword: "${MYSQL_ROOTPWD}"
    password: "${MYSQL_PWD}"

# External MySQL Configuration
# All of these values are only used if `mysql.enabled=false`
externalMysql:
  host: ${MYSQL_HOST}
  port: ${MYSQL_PORT}
  database: "${MYSQL_DB}"
  user: "${MYSQL_USER}"
  password: "${MYSQL_PWD}"

## Use the Redis chart dependency.
redis:
  enabled: ${REDIS_INSTALL}
  auth:
    password: "${REDIS_PWD}"

# External Redis Configuration
# All of these values are only used if `redis.enabled=false`
externalRedis:
  host: ${REDIS_HOST}
  port: ${REDIS_PORT}
  database: ${REDIS_DB}
  password: "${REDIS_PWD}"

concourse:
  concourse:
    web:
      postgres:
        ## Need to be specified if bringing your own PostgreSQL.
        host: ${POSTGRES_HOST}
        port: ${POSTGRES_PORT}
        database: ${POSTGRES_DB}
      sidecarContainers:
        - name: concourse-team-authorized-key-sync
          image: cycloid/concourse-team-authorized-key-sync:latest
          imagePullPolicy: Always
          env:
            - name: VAULT_URL
              value: http://cycloid-vault:8200
            - name: VAULT_ROLE_ID
              value: "${CYCLOID_RO_VAULT_APPROLE_ROLE_ID}"
            - name: VAULT_SECRET_ID
              value: "${CYCLOID_RO_VAULT_APPROLE_SECRET_ID}"
            - name: YAML_KEYS_FILE
              value: /etc/concourse-teams/tsa-team-authorized-keys.yaml
            - name: VERBOSE
              value: "True"
  worker:
    enabled: true
  persistence:
    worker:
      size: 100Gi
  ## Use the PostgreSQL chart dependency.
  postgresql:
    enabled: ${POSTGRES_INSTALL}
    auth:
      password: "${POSTGRES_PWD}"
      postgresPassword: "${POSTGRES_PWD}"
  secrets:
    ## Secrets for DB access if bringing your own PostgreSQL
    postgresUser: ${POSTGRES_USER}
    postgresPassword: ${POSTGRES_PWD}
    localUsers: "cycloid:${CONCOURSE_PWD}"

externalElasticsearch:
  enabled: ${ELASTICSEARCH_ENABLED}
  scheme: https
  host: cost-explorer-es-http
  port: 9200
  username: elastic
  password: ""
  existingSecret: cost-explorer-es-elastic-user
  existingSecretKey: elastic
```

#### Vault Tokens Settings[​](#vault-tokens-settings "Direct link to Vault Tokens Settings")

Lets's now configure the variables in our `values.template.yaml` file. First, set the Cycloid Vault secrets like this:

```
export CYCLOID_VAULT_APPROLE_ROLE_ID=$(cat ./scripts/.out/cycloid-role-id.json | jq -r '.data.role_id')
export CYCLOID_VAULT_APPROLE_SECRET_ID=$(cat ./scripts/.out/cycloid-secret-id.json | jq -r '.data.secret_id')
export CYCLOID_RO_VAULT_APPROLE_ROLE_ID=$(cat ./scripts/.out/cycloid-ro-role-id.json | jq -r '.data.role_id')
export CYCLOID_RO_VAULT_APPROLE_SECRET_ID=$(cat ./scripts/.out/cycloid-ro-secret-id.json | jq -r '.data.secret_id')
```

#### Change default passwords[​](#change-default-passwords "Direct link to Change default passwords")

It is required to change all the default passwords. Let's now generate random ones:

```
export BACKEND_CRYPTO_SIGNING_KEY=$(pwgen -csn 32 1)
export CONCOURSE_PWD=$(pwgen -csn 24 1)
```

#### Domain Names Configuration[​](#domain-names-configuration "Direct link to Domain Names Configuration")

Next, set the domain names for Cycloid console and API like that (for example `api.example.com`):

```
export API_URL=<your_api_url>
export CONSOLE_URL=<your_console_url>
```

#### Configure an SMTP server[​](#configure-an-smtp-server "Direct link to Configure an SMTP server")

Cycloid requires an SMTP server to send emails during the user creation process. Set your SMTP server details like that:

```
export SMTP_HOST=<your_smtp_host:your_smtp_port>
export SMTP_USERNAME=<your_smtp_username>
export SMTP_PASSWORD=<your_smtp_password>
export EMAIL_DEV_MODE=false
```

If you don't have an SMTP server

[Mailhog](https://github.com/codecentric/helm-charts/tree/master/charts/mailhog) will act as a fake smtp server.

First, install [MailHog](https://github.com/codecentric/helm-charts/tree/master/charts/mailhog) Helm repository:

```
helm repo add codecentric https://codecentric.github.io/helm-charts
helm -n ${NAMESPACE} install mailhog codecentric/mailhog
```

Set your SMTP server details like that:

```
export SMTP_HOST=mailhog:1025
export EMAIL_DEV_MODE=true
```

When a user registers, no email is going to be sent, so users will not be able to validate their account. To force new users validation, please run the following script:

```
bash ./scripts/mysql-force-user-email-validation.sh
```

#### MySQL[​](#mysql "Direct link to MySQL")

The easiest and recommended way for trials is to deploy a new database engine on your Kubernetes cluster. To do so, you will need to issue the following commands:

```
export MYSQL_INSTALL=true
export MYSQL_ROOTPWD=$(pwgen -csn 24 1)
export MYSQL_PWD=$(pwgen -csn 24 1)
```

Alternatively, you may want to use an external database. In that case, you'll need to configure the integration like this (adapt the values as required):

```
export MYSQL_INSTALL=false
export MYSQL_HOST=<YOUR_MYSQL_HOST>
export MYSQL_PORT=3306
export MYSQL_DB=cycloid
export MYSQL_USER=cycloid
export MYSQL_PWD=<YOUR_MYSQL_PASSWORD>
```

#### Redis[​](#redis "Direct link to Redis")

The easiest and recommended way for trials is to deploy a new database engine on your Kubernetes cluster. To do so, you will need to issue the following commands:

```
export REDIS_INSTALL=true
export REDIS_PWD=$(pwgen -csn 24 1)
```

Alternatively, you may want to use an external database. In that case, you'll need to configure the integration like this (adapt the values as required):

```
export REDIS_INSTALL=false
export REDIS_HOST=<YOUR_REDIS_HOST>
export REDIS_PORT=6379
export REDIS_DB=0
export REDIS_PWD=<YOUR_REDIS_PASSWORD>
```

#### PostgreSQL[​](#postgresql "Direct link to PostgreSQL")

The easiest and recommended way for trials is to deploy a new database engine on your Kubernetes cluster. To do so, you will need to issue the following commands:

```
export POSTGRES_INSTALL=true
export POSTGRES_PWD=$(pwgen -csn 24 1)
```

Alternatively, you may want to use an external database. In that case, you'll need to configure the integration like this (adapt the values as required):

```
export POSTGRES_INSTALL=false
export POSTGRES_HOST=<YOUR_POSTGRES_HOST>
export POSTGRES_PORT=5432
export POSTGRES_DB=atc
export POSTGRES_USER=cycloid
export POSTGRES_PWD=<YOUR_POSTGRES_PASSWORD>
```

#### ElaticSearch[​](#elaticsearch "Direct link to ElaticSearch")

If you previously installed ElasticSearch to use Cloud Cost Management, you'll need to enable this integration like this:

```
export ELASTICSEARCH_ENABLED=true
```

Otherwise, you will need to explicitely disable this integration like this:

```
export ELASTICSEARCH_ENABLED=false
```

#### Variables substitution[​](#variables-substitution "Direct link to Variables substitution")

We're all set to create our `values.custom.yaml` file. Let's issue the following command:

```
envsubst < values.template.yaml > values.custom.yaml
```

#### Custom modifications[​](#custom-modifications "Direct link to Custom modifications")

Review the `values.custom.yaml` file for additional configuration that you might want to do, like to set up your TLS secrets to enable HTTPS.

### Install the rest of the Cycloid set up[​](#install-the-rest-of-the-cycloid-set-up "Direct link to Install the rest of the Cycloid set up")

Run the `cy-ecr-token-helper` job to generate `cycloid-ecr` secret:

```
kubectl -n $NAMESPACE create job --from=cronjob/cy-ecr-token-helper cy-ecr-token-helper-001
```

Install the other components:

```
helm upgrade -n ${NAMESPACE} --values values.custom.yaml cycloid .
```

### Set your DNS Records[​](#set-your-dns-records "Direct link to Set your DNS Records")

Create two CNAME records in your DNS zone for the Cycloid console and API according to your settings above. Let these records point to your external DNS name exposed by the Kubernetes `Service`.

You can get the external DNS address to use in your CNAME records by listing the ingress like this:

```
kubectl get ing -n ${NAMESPACE}
```

tip

A few minutes may be required for the records to propagate to your DNS.

### Set up the initial Cycloid Console user and organization[​](#set-up-the-initial-cycloid-console-user-and-organization "Direct link to Set up the initial Cycloid Console user and organization")

1. In your favorite browser, go to `/signup` at your console domain, for example `https://console.example.com/signup`

2. Fill in the form to register you as the first admin user.

3. If you have configured an SMTP server, please go to your email and validate your user email. Otherwise, if you don't have an SMTP server, run this script to activate all registered users at once:

```
bash ./scripts/mysql-force-user-email-validation.sh
```

4. Go back to the console homepage and login, then create the root organization as requested.

5. Enter the license key provided by Cycloi to activate your platform.

## Frequenly Asked Questions[​](#frequenly-asked-questions "Direct link to Frequenly Asked Questions")

### Upgrade the Cycloid Console versions[​](#upgrade-the-cycloid-console-versions "Direct link to Upgrade the Cycloid Console versions")

You can use a specific Cycloid Console and API releases by changing the following `tag` parameters in your `values.custom.yaml` file:

* `frontend.image.tag`
* `backend.image.tag`

For the latest public release, set this tag to `latest-public`.

Then upgrade your deployed helm release with the following:

```
helm upgrade -n ${NAMESPACE} --values values.custom.yaml cycloid . 
```

Caution

The AWS ECR password in the docker-registry secret provided by the AWS CLI may expire after 12 hours. If you are upgrading your Helm release and are experiencing `ErrImagePull` and/or `ImagePullBackOff` errors, you will have to delete the `cycloid-ecr` secret and re-create it as described [here](#renew-the-docker-registry-token).


---

# Cycloid Self-Hosted Kubernetes

The Cycloid on-premises setup on Kubernetes provide a way to setup the Cycloid platform and dependencies within your own Kubernetes cluster.

This setup is provided as a [Helm chart](https://helm.sh/docs/topics/charts/) which is kind of the de facto standard to package applications for Kubernetes.

warning

To access our private Docker registry, you will need to obtain credentials from Cycloid.

## Requirements[​](#requirements "Direct link to Requirements")

In order to make use of this setup, you will need the following:

* Cluster

  <!-- -->

  * Kubernetes cluster version: `>= 1.23.0`.
  * Make sure your `kubectl` context is targeting the intended cluster and namespace for the Cycloid setup.
  * A working [Kubernetes Ingress Controller](https://kubernetes.io/docs/concepts/services-networking/ingress-controllers/) installed within the cluster to access the Cycloid Console.
  * Set k8s ingress controller or the ingress configuration to allow HTTP requests that can have multiple Mb. This is usually the case when using cycloid's inventory feature and without, this configuration enabled, you migth have an error as follows: "413 Payload Too Large". For example for the nginx-controller this is done in the ingress directly by setting an annotation as follows: `"nginx.ingress.kubernetes.io/proxy-body-size: 20m"`
  * Working DNS records pointing to your Kubernetes cluster for the Console and API domains you intend to use.

* Locally

  <!-- -->

  * [Helm v3](https://helm.sh/docs/intro/install/).
  * [AWS CLI](https://docs.aws.amazon.com/fr_fr/cli/latest/userguide/cli-chap-install.html).
  * The [jq](https://stedolan.github.io/jq/) utility if you want to make use of the convenient script automation during the Vault configuration.

## Prerequisites[​](#prerequisites "Direct link to Prerequisites")

### 1 - Setup the required secret to access the Cycloid docker images[​](#1---setup-the-required-secret-to-access-the-cycloid-docker-images "Direct link to 1 - Setup the required secret to access the Cycloid docker images")

To access Cycloid docker images, you need to create an Image Pull Secret.This allows your cluster to connect to our Container Registry and pull the image itself.

Please make sure to set the right `NAMESPACE` where Cycloid should be installed

```
export SCW_SECRET_KEY=...
export NAMESPACE=cycloid

kubectl -n ${NAMESPACE} create secret docker-registry scw-registry-secret --docker-server=rg.fr-par.scw.cloud --docker-username=nologin --docker-password=$SCW_SECRET_KEY
```

### 2 - Add the Cycloid on-premises Helm repository[​](#2---add-the-cycloid-on-premises-helm-repository "Direct link to 2 - Add the Cycloid on-premises Helm repository")

```
# Add the cycloid-onprem helm repository to helm locally
helm repo add cycloid-onprem https://cycloid-onprem-helm-charts.s3.amazonaws.com/stable/cycloid/

# Verify that helm can see the cycloid-onprem/cycloid chart
helm search repo cycloid-onprem/cycloid
```

## Installation[​](#installation "Direct link to Installation")

The Cycloid Helm chart differs significantly from many other Helm charts because it deploys not just the Cycloid application but also the platform's infrastructure and dependencies. This complexity means the chart installation is divided into two major steps:

* Installation and/or configuration of the [Hashicorp Vault](https://www.hashicorp.com/products/vault) dependency.
* Installation of the rest of the Cycloid stack

To set up the Helm chart, it is necessary to pull it locally, at least for the initial setup. This is because essential resources like scripts and the values.sample.yaml file are included in the chart and must be accessed directly to properly configure the deployment.

### 1 - Pull the Cycloid on-premises Helm chart locally[​](#1---pull-the-cycloid-on-premises-helm-chart-locally "Direct link to 1 - Pull the Cycloid on-premises Helm chart locally")

```
# Pull the helm chart
helm pull --untar cycloid-onprem/cycloid --untardir cycloid-release

# or if you want to pull a specific version
helm pull --untar cycloid-onprem/cycloid --untardir cycloid-release --version <version>
```

### 2 - Create your Cycloid installation directory[​](#2---create-your-cycloid-installation-directory "Direct link to 2 - Create your Cycloid installation directory")

* Kubernetes
* Openshift

```
# Create your cycloid installation directory
mkdir cycloid

# Retrieve the scripts from the Helm release and create your values.custom.yaml based on the provided sample file to include your custom modifications
cp -a cycloid-release/cycloid/scripts cycloid/
cp -a cycloid-release/cycloid/values.sample.yaml cycloid/values.custom.yaml

# Clean the local release
rm -r cycloid-release
```

```
# Create your cycloid installation directory
mkdir cycloid

# Retrieve the scripts from the Helm release and create your values.custom.yaml based on the provided sample file to include your custom modifications
cp -a cycloid-release/cycloid/scripts cycloid/
cp -a cycloid-release/cycloid/values.sample.yaml cycloid/values.custom.yaml
cp -a cycloid-release/cycloid/values.openshift.yaml cycloid/values.openshift.custom.yaml

# Clean the local release
rm -r cycloid-release
```

The `cycloid` directory will store your custom configuration (`values.custom.yaml`) and other files generated during the installation process. Ensure you back it up securely.

### 3 - Setup Vault[​](#3---setup-vault "Direct link to 3 - Setup Vault")

Important

By default, Vault stores its data in a local PersistentVolumeClaim (PVC). You can also configure it to use [MySQL](/cookbook/dedicated-platform/advanced-configurations/vault.md#mysql-storage-backend) or [another external storage backend](https://developer.hashicorp.com/vault/docs/configuration/storage/mysql) for improved scalability and resilience.

#### 3.1 Installation[​](#31-installation "Direct link to 3.1 Installation")

Install only the Vault service using the Helm chart.

* Kubernetes
* Openshift

```
cd cycloid

# Use --version for a specific release
helm install -n ${NAMESPACE} \
    --values values.custom.yaml \
    --set frontend.enabled=false \
    --set backend.enabled=false \
    --set mysql.enabled=false \
    --set redis.enabled=false \
    --set concourse.enabled=false \
    cycloid cycloid-onprem/cycloid
```

```
cd cycloid

# Use --version for a specific release
helm install -n ${NAMESPACE} \
    --values values.custom.yaml \
    --values values.openshift.custom.yaml \
    --set frontend.enabled=false \
    --set backend.enabled=false \
    --set mysql.enabled=false \
    --set redis.enabled=false \
    --set concourse.enabled=false \
    cycloid cycloid-onprem/cycloid
```

#### 3.2 - Initialization[​](#32---initialization "Direct link to 3.2 - Initialization")

Caution

Avoid running the `vault-init.sh` script on an already installed Cycloid Onprem environment unless you intend to reset and reinstall it from scratch.

Run the Vault init script in order to:

* Initialize Vault root token, unseal keys and storage
* [Unsealed](https://developer.hashicorp.com/vault/docs/configuration/seal) Vault
* Enable "kv" storage mountpoint
* Create login access via approle used by Cycloid API

```
bash ./scripts/vault-init.sh
```

Important

Vault needs to be unsealed each time it restarts. To unseal it, please follow the instructions outlined in the [**How to Unseal Vault manually**](/cookbook/dedicated-platform/setup-k8s.md#how-to-unseal-vault-manually) procedure.

### 4 - Chart Configuration (values.custom.yaml)[​](#4---chart-configuration-valuescustomyaml "Direct link to 4 - Chart Configuration (values.custom.yaml)")

During this step we are going to go through few changes that has to be made in `values.custom.yaml` file.

Important

**Backup Your Cycloid Directory**

At this stage, it is **mandatory to back up** your Cycloid directory. This directory includes:

* Files generated by Vault, located in the `scripts/.out/` subdirectory.
* Your custom configuration file, `values.custom.yaml`.

The Cycloid directory is **essential for upgrading** the Cycloid platform. It contains your unique configuration and critical information, including:

* Vault unseal keys.
* The initial root tokens.
* AppRole credentials required for the Cycloid platform to operate properly.

Failing to back up this directory could result in the loss of vital data, potentially affecting the functionality and security of your Cycloid platform.

#### 4.1 - Required[​](#41---required "Direct link to 4.1 - Required")

**Security - change all default password and keys** Change all the default passwords and keys. you can do either manually or by simply calling our automated script.

For you convenience, you can use the following command. It will replace default patterns by random password:

```
bash ./scripts/generate-random-passwords.sh
```

How to do it manually ?

Here is the list of all password fields to changes and the pattern to replace (You can generate random password for example using the following command `pwgen 32 1`):

| **Field**                                    | **Pattern**                                      |
| -------------------------------------------- | ------------------------------------------------ |
| `backend.cryptoSigningKey`                   | `##backend-cryptoSigningKey##`                   |
| `backend.concourse.password`                 | `##concourse-password##`                         |
| `backend.jwtKey1`                            | `##backend-jwtKey1##`                            |
| `concourse.secrets.localUsers`               | `##concourse-password##`                         |
| `mysql.auth.rootPassword`                    | `##mysql-auth-rootPassword##`                    |
| `mysql.auth.password`                        | `##mysql-auth-password##`                        |
| `redis.auth.password`                        | `##redis-auth-password##`                        |
| `concourse.postgresql.auth.postgresPassword` | `##concourse-postgresql-auth-postgresPassword##` |
| `concourse.postgresql.auth.password`         | `##concourse-postgresql-auth-password##`         |

Here is the list of all keys fields to changes and the pattern to replace (You can follow [this guide](https://concourse-ci.org/concourse-generate-key.html) in order to generate keys):

| **Field**                             | **Pattern**                               |
| ------------------------------------- | ----------------------------------------- |
| `concourse.secrets.hostKey`           | `##concourse-secrets-hostKey##`           |
| `concourse.secrets.hostKeyPub`        | `##concourse-secrets-hostKeyPub##`        |
| `concourse.secrets.sessionSigningKey` | `##concourse-secrets-sessionSigningKey##` |
| `concourse.secrets.workerKey`         | `##concourse-secrets-workerKey##`         |
| `concourse.secrets.workerKeyPub`      | `##concourse-secrets-workerKeyPub##`      |

**SMTP - configuration**: Emails will be sent by Cycloid, mainly during the user creation process and to notify users when they has been invited to join an organization.

Replace the following with your SMTP server information:

| **Field**                                  | **Pattern**               |
| ------------------------------------------ | ------------------------- |
| `backend.extraEnvVars.EMAIL_SMTP_SVR_ADDR` | `##smtp-host:smtp-port##` |
| `backend.extraEnvVars.EMAIL_SMTP_USERNAME` | `##smtp-username##`       |
| `backend.extraEnvVars.EMAIL_SMTP_PASSWORD` | `##smtp-password##`       |

Note

Only for POC: If you don't have SMTP server [Mailhog](https://github.com/codecentric/helm-charts/tree/master/charts/mailhog) can be used by following the [How to test Cycloid without valide SMTP server](/cookbook/dedicated-platform/advanced-configurations/smtp-configuration.md#fake-smtp-server-for-testing-and-debugging-purposes-only)

**DNS - access URL's** Define the DNS entries to be used for kubernetes ingress in order to access to Cycloid platform.

The default values that has to be replace by your desired ones are:

* Console: `console.cycloid.local`
* API: `api.cycloid.local`

For you convenience, you can use the following command:

* Kubernetes
* Openshift

```
API_URL=api-example.cycloid.io
CONSOLE_URL=console-example.cycloid.io

sed -i "s/console.cycloid.local/$CONSOLE_URL/;s/api.cycloid.local/$API_URL/;" values.custom.yaml
```

```
API_URL=api-example.cycloid.io
CONSOLE_URL=console-example.cycloid.io

sed -i "s/console.cycloid.local/$CONSOLE_URL/;s/api.cycloid.local/$API_URL/;" values.custom.yaml values.openshift.custom.yaml
```

note

The chart is going to create Ingress. Please ensure a working **Ingress Controller** is deployed within your Kubernetes cluster. The default Ingress resources are setup to work with the NGINX Ingress Controller out of the box. You will also need to make sure the **DNS records used** for your customized domains are working in order to have access to the Console after the installation.

**Databases - access configuration**: Cycloid require databases services. You can provide your own databases url/access or deploy databases containers using our helm chart.

Data Persistence

If you are using databases setup provided in our chart, by default, components like MySQL, Redis, and Vault use persistent volumes to retain their data. Ensure that you have a default [StorageClass](https://kubernetes.io/docs/concepts/storage/storage-classes/) configured, or specify a custom one.

* **MySQL** Let all default values if you want to use the provided one, otherwise set `mysql.enabled` to `false` and setup the `externalMysql.*` parameters accordingly to your external MySQL.

* **Redis** Let all default values if you want to use the provided one, otherwise set `redis.enabled` to `false` and setup the `externalRedis.*` parameters accordingly to your external Redis.

* **PostgreSQL** Let all default values if you want to use the provided one, otherwise set `concourse.postgresql.enabled` to `false` and setup the following parameters accordingly to your external PostgreSQL:

  * `concourse.concourse.web.postgres.host`
  * `concourse.concourse.web.postgres.port`
  * `concourse.concourse.web.postgres.database`
  * `concourse.secrets.postgresUser`
  * `concourse.secrets.postgresPassword`

#### 4.2 - Custom modifications[​](#42---custom-modifications "Direct link to 4.2 - Custom modifications")

Check the `values.custom.yaml` file for additional configuration that you might want to take a look at, like enabling Ingress access to Concourse and Vault UI or setup your TLS secrets to enable HTTPS.

### 5 - Install the rest of the Cycloid setup[​](#5---install-the-rest-of-the-cycloid-setup "Direct link to 5 - Install the rest of the Cycloid setup")

Install the other components

* Kubernetes
* Openshift

```
# Use --version for a specific release
helm upgrade -n ${NAMESPACE} --values values.custom.yaml cycloid cycloid-onprem/cycloid
```

```
# Use --version for a specific release
helm upgrade -n ${NAMESPACE} --values values.custom.yaml --values values.openshift.custom.yaml cycloid cycloid-onprem/cycloid
```

### 6 - Setup the initial Cycloid Console user and organization[​](#6---setup-the-initial-cycloid-console-user-and-organization "Direct link to 6 - Setup the initial Cycloid Console user and organization")

* Connect to the Cycloid Console using the URL you've configured in the `values.custom.yml` file (the default one being [console.cycloid.local](http://console.cycloid.local)).
* Create the first user by accessing the `https://<cycloid-console>/signup` page.
* Create the first and root organization.

## Upgrades[​](#upgrades "Direct link to Upgrades")

### Upgrade the Cycloid Console versions[​](#upgrade-the-cycloid-console-versions "Direct link to Upgrade the Cycloid Console versions")

Important

Ensure that all commands related to the upgrade are executed **from the backed-up Cycloid directory** [described above](/cookbook/dedicated-platform/setup-k8s.md#4---chart-configuration-valuescustomyaml). This guarantees the use of the correct configuration and prevents potential issues during the process.

To upgrade to newer Cycloid Console frontend and API versions, modify the following `tag` parameters in your `values.custom.yaml` file:

* `frontend.image.tag`
* `backend.image.tag`

Then, upgrade your deployed Helm release using the following command:

* Kubernetes
* Openshift

```
# From your parent directory

# Update the cycloid-onprem repo locally
helm repo update cycloid-onprem

# Get the latest chart
helm pull --untar cycloid-onprem/cycloid --untardir cycloid-release

# Retrieve the latest scripts
rsync -avz cycloid-release/cycloid/scripts/ cycloid/scripts/

# Clean the local release
rm -r cycloid-release

# Upgrade your installation
helm upgrade -n ${NAMESPACE} --values values.custom.yaml cycloid cycloid-onprem/cycloid
```

```
# From your parent directory

# Update the cycloid-onprem repo locally
helm repo update cycloid-onprem

# Get the latest chart
helm pull --untar cycloid-onprem/cycloid --untardir cycloid-release

# Retrieve the latest scripts
rsync -avz cycloid-release/cycloid/scripts/ cycloid/scripts/

# Clean the local release
rm -r cycloid-release

# Upgrade your installation
helm upgrade -n ${NAMESPACE} --values values.custom.yaml --values values.openshift.custom.yaml cycloid cycloid-onprem/cycloid
```

**Reminder:** Always double-check that the `values.custom.yaml` file is from the backed-up directory to ensure the integrity of the upgrade process.

## Helm releases upgrade and migration[​](#helm-releases-upgrade-and-migration "Direct link to Helm releases upgrade and migration")

### From 0.14.1 to 0.15.0[​](#from-0141-to-0150 "Direct link to From 0.14.1 to 0.15.0")

Due to Bitnami's recent policy changes, Cycloid has decided to move away from Bitnami images and return to using official Docker images. This entails two main changes: the Docker image repository being used and the Helm chart dependencies.

**Redis**

warning

**Breaking change**: if you’re installing Redis via the Cycloid Helm Chart or Ansible Playbook

The Docker image repository has changed from `bitnami/redis` to `redis`. If you are using network filtering or a Docker mirror repository, please update it to reference the new image.

* Cycloid Self-Hosted Kubernetes

Since Helm and the StatefulSet volumes have changed, running a helm upgrade will fail with the following error:

```
Error: UPGRADE FAILED: cannot patch "cycloid-redis-master" with kind StatefulSet: StatefulSet.apps "cycloid-redis-master" is invalid: spec: Forbidden: updates to statefulset spec for fields other than 'replicas', 'ordinals', 'template', 'updateStrategy', 'persistentVolumeClaimRetentionPolicy' and 'minReadySeconds' are forbidden
```

To proceed, you must delete the existing cycloid-redis-master StatefulSet before performing the upgrade:

```
kubectl delete sts cycloid-redis-master
```

**Mysql**

warning

**Breaking change**: if you’re installing Mysql via the Cycloid Helm Chart or Ansible Playbook

The Docker image repository has changed from `bitnami/mysql` to `mysql`. If you are using network filtering or a Docker mirror repository, please update it to reference the new image.

* Cycloid Self-Hosted Kubernetes

Since Helm and the StatefulSet volumes have changed, running a helm upgrade will fail with the following error:

```
Error: UPGRADE FAILED: cannot patch "cycloid-mysql" with kind StatefulSet: StatefulSet.apps "cycloid-mysql" is invalid: spec: Forbidden: updates to statefulset spec for fields other than 'replicas', 'ordinals', 'template', 'updateStrategy', 'persistentVolumeClaimRetentionPolicy' and 'minReadySeconds' are forbidden
```

To proceed, you must delete the existing cycloid-mysql StatefulSet before performing the upgrade:

```
kubectl delete sts cycloid-mysql
```

**Postgres**

warning

**Breaking change**: if you’re installing Postgres via the Cycloid Helm Chart or Ansible Playbook

The Docker image repository has changed from `bitnami/postgres` to `postgres`. If you are using network filtering or a Docker mirror repository, please update it to reference the new image.

* Cycloid Self-Hosted Kubernetes

Since Helm and the StatefulSet volumes have changed, running a helm upgrade will fail with the following error:

```
Error: UPGRADE FAILED: cannot patch "cycloid-concourse-postgresql" with kind StatefulSet: StatefulSet.apps "cycloid-concourse-postgresql" is invalid: spec: Forbidden: updates to statefulset spec for fields other than 'replicas', 'ordinals', 'template', 'updateStrategy', 'persistentVolumeClaimRetentionPolicy' and 'minReadySeconds' are forbidden
```

To proceed, you must delete the existing cycloid-concourse-postgresql StatefulSet before performing the upgrade:

```
kubectl delete sts cycloid-concourse-postgresql
```

### From 0.13.2 to 0.14.0[​](#from-0132-to-0140 "Direct link to From 0.13.2 to 0.14.0")

warning

**Breaking change**: if you’re installing MySQL via the Cycloid Helm Chart or Ansible Playbook

In our latest release, we’ve upgraded **MySQL** support from version `8.0.36` to `8.4.3`, introducing several improvements. However, if you’re installing MySQL via the Cycloid Helm Chart or Ansible Playbook, please be aware of an important breaking change related to authentication methods.

MySQL has switched from using the `mysql_native_password` authentication plugin to the `caching_sha2_password` plugin. This change enhances security and performance but requires any previously created database user passwords to be updated with (SHA-2 encryption)\[<https://dev.mysql.com/doc/refman/8.4/en/caching-sha2-pluggable-authentication.html>].

To update your user password **BEFORE** the upgrade, please follow the guide below:

Get the previous root and cycloid password

* Cycloid Self-Hosted Kubernetes
* Cycloid Self-Hosted Instances

```
kubectl get secret cycloid-mysql -o json | jq -r '.data."mysql-password"' | base64 -d
kubectl get secret cycloid-mysql -o json | jq -r '.data."mysql-root-password"' | base64 -d
```

```
cat /etc/default/cycloid-db
```

[Connect to mysql](/reference/dedicated-platform/troubleshooting.md#how-locally-access-to-the-cycloid-database-) but with the **root** account.

Please run the following command, ensuring you set the correct password

```
# Check database users plugins
SELECT user, host, plugin FROM mysql.user;

# Update root and cycloid password with sha2
ALTER USER 'cycloid'@'%' IDENTIFIED WITH 'caching_sha2_password' BY 'password';
ALTER USER 'root'@'%' IDENTIFIED WITH 'caching_sha2_password' BY 'password';
```

An alternative solution (not recommended) is to continue using the native plugin

However, be aware that it will be deprecated and removed in MySQL 9.0. To keep the native plugin enabled, override the [mysql.primary.configuration](https://github.com/bitnami/charts/blob/main/bitnami/mysql/values.yaml#L216) to add `mysql_native_password=ON`

Example:

values.custom.yaml

```
  mysql:
    primary:
      configuration: |-
        [mysqld]
        mysql_native_password=ON
        ...
```

warning

**Breaking change**: if you’re installing PostgreSQL via the Cycloid Helm Chart or Ansible Playbook

In our latest release, we’ve upgraded **PostgreSQL** support from version **14 to 15**. Note that local data from PostgreSQL 14 is not compatible with PostgreSQL 15, so it is essential to **backup your PostgreSQL databases and clean old datas before** proceeding with the upgrade and then restore them afterward. To assist with the process, you can refer to [this documentation](/reference/dedicated-platform/troubleshooting.md#how-locally-access-to-the-concourse-database-)

warning for AWS RDS PostgreSQL

By default, Concourse does not use an SSL connection for PostgreSQL. However, RDS PostgreSQL 15 enables the `rds.force_ssl` parameter by default, requiring SSL for all connections. To ensure compatibility, set `rds.force_ssl` to `false` in your RDS parameter group if SSL is not configured in Concourse.

An alternative solution (not recommended) is to continue using postgres 14

* Cycloid Self-Hosted Kubernetes
* Cycloid Self-Hosted Instances

values.custom.yaml

```
concourse:
  postgresql:
    image:
      tag: 14.13.0
```

```
concourse_db_image: postgres:14.13
```

Once done, you can proceed with the upgrade.

## Frequenly Asked Question[​](#frequenly-asked-question "Direct link to Frequenly Asked Question")

### How to create users on Cycloid console ?[​](#how-to-create-users-on-cycloid-console- "Direct link to How to create users on Cycloid console ?")

The signup button is hidden by default but the functionality available by accessing the `console URL`+`/signup`

Example: `https://console.cycloid.local/signup`

### How to connect an external worker to my onprem setup ?[​](#how-to-connect-an-external-worker-to-my-onprem-setup- "Direct link to How to connect an external worker to my onprem setup ?")

The first step is to expose the Concourse worker gateway port of the Concourse web server to allow external Concourse workers usage.

In order for your external workers to join the Concourse server included in this chart, you will need to expose the Concourse worker gateway port. This can be achieved in most managed Kubernetes clusters by creating a Kubernetes Service of type `LoadBalancer`.

For e.g. using the following manifest:

```
apiVersion: v1
kind: Service
metadata:
  name: cycloid-concourse-web-worker-gateway-custom
  # namespace: your-namespace
  labels:
    app: cycloid-concourse-web
spec:
  type: LoadBalancer
  ports:
  - name: worker-gateway
    port: 2222
    protocol: TCP
    targetPort: tsa
  selector:
    app: cycloid-concourse-web
```

Then follow the docs to create [external workers](/reference/ci-cd-pipelines/concepts/workers/.md) with Cycloid and make sure to override the following fields:

* **Scheduler API URL** also called `concourse_tsa_host`: It is the `External IP` from the previously created `cycloid-concourse-web-worker-gateway-custom` svc. Please add `https://`.

It can be retrieve with the following command:

```
kubectl -n $NAMESPACE get service cycloid-concourse-web-worker-gateway-custom -o template --template="{{.spec.loadBalancerIP}}"
```

* **Scheduler host**: same as above but without the `https://`

* **Scheduler port**: It is the `port` from the previouly created `cycloid-concourse-web-worker-gateway-custom` svc. (default 2222)

* **Scheduler TSA public key**: SSH public key from your `value.yml` under `concourse.secrets.hostKeyPub`

### How to enable console-wide concourse worker running in the Kubernetes cluster[​](#how-to-enable-console-wide-concourse-worker-running-in-the-kubernetes-cluster "Direct link to How to enable console-wide concourse worker running in the Kubernetes cluster")

We usually recommend using [external workers](/reference/ci-cd-pipelines/concepts/workers/.md) with Cycloid.

But if you are interested in running global Kubernetes Concourse workers shared across all the organizations of your setup, here are the following configuration steps to make it work.

In your `values.custom.yaml`, you should be able to see `worker` sub-section within the `concourse` block. Changing the `enabled` field to `true` will enable the concourse worker statefulset included in the concourse sub-helm chart and deploy a number of replicas equivalent to the `replicas` field. The resources attributed to each worker can be modified in the `worker.resources` and `persistence.worker` sub-sections.

For e.g.

values.custom.yaml

```
…
concourse:
  …
  worker:
    ## Enable or disable the worker component.
    ## This can allow users to create web only releases by setting this to false
    ##
    enabled: true

    ## Number of replicas.
    ##
    replicas: 2

    ## Configure resource requests and limits.
    ## Ref: https://kubernetes.io/docs/user-guide/compute-resources/
    ##
    resources:
      requests:
        cpu: "2"
        memory: "4Gi"
      limits:
        cpu: "2"
        memory: "4Gi"

    ## Node selector for the worker nodes.
    ## Ref: https://kubernetes.io/docs/concepts/configuration/assign-pod-node/#nodeselector
    ##
    nodeSelector:
      "kubernetes.io/os": linux

  persistence:
    enabled: true
    worker:
      ## concourse data Persistent Volume Storage Class
      ## If defined, storageClassName: <storageClass>
      ## If set to "-", storageClassName: "", which disables dynamic provisioning
      ## If undefined (the default) or set to null, no storageClassName spec is
      ##   set, choosing the default provisioner.  (gp2 on AWS, standard on
      ##   GKE, AWS & OpenStack)
      ##
      storageClass:

      ## Persistent Volume Access Mode.
      ##
      accessMode: ReadWriteOnce

      ## Persistent Volume Storage Size.
      ##
      size: 100Gi
…
```

Don't forget to upgrade your Helm release to take your changes into account:

* Kubernetes
* Openshift

```
helm upgrade -n ${NAMESPACE} --values values.custom.yaml cycloid .
```

```
helm upgrade -n ${NAMESPACE} --values values.custom.yaml --values values.openshift.custom.yaml cycloid .
```

### How to Unseal Vault manually[​](#how-to-unseal-vault-manually "Direct link to How to Unseal Vault manually")

When a Vault server is started, it starts in a [sealed](https://developer.hashicorp.com/vault/docs/configuration/seal) state and it does not know how to decrypt data. Unsealing is the process of providing decryption key to decrypt the data.

You will need to enter 3 Vault Unseal Keys created in the previous Initialization step (and saved for your convenience in `scripts/.out/vault-init.json`).

```
bash ./scripts/vault-unseal.sh
```

Vault has to be unseal anytime it start. If you need to automate it, you can configure auto-unsealing.

Auto-unsealing (optional)

Vault supports opt-in automatic unsealing via cloud technologies: AliCloud KMS, [AWS KMS](https://developer.hashicorp.com/vault/tutorials/auto-unseal/autounseal-aws-kms), [Azure Key Vault](https://developer.hashicorp.com/vault/tutorials/auto-unseal/autounseal-azure-keyvault), [Google Cloud KMS](https://developer.hashicorp.com/vault/tutorials/auto-unseal/autounseal-gcp-kms), and OCI KMS. This feature enables operators to delegate the unsealing process to trusted cloud providers to ease operations in the event of partial failure and to aid in the creation of new or ephemeral clusters.

If Auto-unsealing is required, we highly recommend utilizing one of the supported options mentioned. However, for a more straightforward solution, the [**Vault Auto Unseal configuration**](/cookbook/dedicated-platform/advanced-configurations/vault.md#auto-unseal-configuration) can be employed.


---

# Cycloid Self-Hosted Instances

The Cycloid on-premises setup allows you to deploy the Cycloid platform and its dependencies on one or several servers using Docker.

Warning

The Cycloid on-premises setup is hosted in a private Git repository: [ansible-cycloid-onprem](https://github.com/cycloidio/ansible-cycloid-onprem).

To access and run it, you must obtain from Cycloid a dedicated SSH key for the Git repository and Scaleway IAM credentials for the private Docker registry.

* Regular install
* High availability (HA) install
* High Availability (HA) with external vault installation

Regular installation includes all the components required for Cycloid. During setup, you can choose to deploy everything on a single server or distribute the services across multiple servers.

![Schema](/assets/images/onprem-c497b70a525c6aa92f3bd1ff479dbb94.png)

High Availability (HA) Installation This configuration provisions two identical servers running Cycloid services.

It requires three supporting services:

* Vault external storage backend
* MySQL database
* PostgreSQL database

In most cases, these services are provided via managed offerings from cloud providers (e.g., AWS RDS) or managed internally by a DBA team for on-premises environments.

This setup is very similar to the HA installation with an external Vault, except that the Vault server itself is deployed on the Cycloid servers. In this case, only an external storage backend for Vault is required. Possible backends include a Consul cluster, a MySQL server, or a shared NFS filesystem. ![Schema](/assets/images/onprem-ha-f2f2d129d7cb64998e308ab4ee176516.png)

High Availability (HA) Installation with External Vault This configuration provisions two identical servers running Cycloid services.

It requires three supporting services:

* Vault
* MySQL database
* PostgreSQL database

As with the standard HA setup, these services are typically provided via managed cloud offerings (e.g., AWS RDS) or managed internally by a DBA team for on-premises environments. ![Schema](/assets/images/onprem-ha-vault-07832f89b6052ab23ffe9914b3f9f22b.png)

After running this playbook with the default configuration on a server, the following services will be installed and available:

| **Service**                | **Port**                               |
| -------------------------- | -------------------------------------- |
| `Concourse web`            | TSA `2222`, WEB `8080`, WEB SSL `8443` |
| `Concourse db`             | `5432`                                 |
| `vault`                    | `8200`                                 |
| `Cycloid frontend`         | `3000`                                 |
| `Cycloid api`              | `3001`                                 |
| `Cycloid api task-manager` | `2112`                                 |
| `Cycloid db`               | `3306`                                 |
| `Nginx proxy`              | HTTP `80`, HTTPS `443`                 |
| `ElasticSearch`            | HTTPS `9200`                           |

## Requirements[​](#requirements "Direct link to Requirements")

The VM must have at least **4 CPUs**, **8 GB of RAM**, and a **100 GB SSD**.

The following operating systems are validated in our CI pipeline:

| **Operating system** | **version**   | **tests**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| -------------------- | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Debian**           | bullseye (11) | ![check](data:image/png;base64,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) |
| **Ubuntu**           | 22.04         | ![check](data:image/png;base64,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) |

## Installation[​](#installation "Direct link to Installation")

warning

Note: Before running the Ansible playbook, make sure that virtualenv, pip, and all required dependencies are installed and properly configured on your system

```
apt-get install git build-essential python3-dev python3-pip python3-venv libssl-dev libffi-dev
```

### Common tasks[​](#common-tasks "Direct link to Common tasks")

All sample playbooks and their requirements are available in the `playbooks` directory. To get started, create a working directory and copy the files you plan to use into it

```
# This require to use the SSH key provided by Cycloid
git clone git@github.com:cycloidio/ansible-cycloid-onprem.git
mkdir cycloid-onprem
cd cycloid-onprem
cp -r ../ansible-cycloid-onprem/playbooks/* .
```

Set up a Python virtual environment and install Ansible along with all required Python libraries

```
python3 -m venv venv --clear
source venv/bin/activate
export ANSIBLE_PYTHON_INTERPRETER=/usr/bin/python3
python3 -m pip install --upgrade pip
python3 -m pip install -U -r pip-requirements.txt
```

Cycloid Docker images are hosted in a Scaleway container repository. Before running the playbook, export the Scaleway access key provided by Cycloid to access the repository

```
# Require Scaleway creds provided by Cycloid
export SCW_SECRET_KEY=SCW...
export SCW_ACCESS_KEY=...
```

Generate an SSH key pair to configure the Cycloid pipeline engine based on Concourse

```
mkdir keys
ssh-keygen -m pem -t rsa -b 2048 -N '' -C '' -f keys/id_rsa
```

### Cycloid core installation[​](#cycloid-core-installation "Direct link to Cycloid core installation")

Download the necessary Ansible roles to set up the Cycloid core

```
ansible-galaxy role install -r requirements.yml -p roles -v --force
ansible-galaxy collection install -r requirements.yml -p collections -v --force
```

Create an Ansible inventory file with the server IP (`1.2.3.4`) where Cycloid will be installed.

* Regular install
* HA High Availability (HA) install
* High Availability (HA) install with external Vault

```
cat >> inventory <<EOF
[cycloid]
1.2.3.4

# Meta groups to setup all in one
[cycloid_core:children]
cycloid
[cycloid_scheduler:children]
cycloid
[cycloid_scheduler_db:children]
cycloid
[cycloid_cache:children]
cycloid
[cycloid_db:children]
cycloid
[cycloid_creds:children]
cycloid
[smtp_server:children]
cycloid
#[minio:children]
#cycloid
#[elasticsearch:children]
#cycloid

EOF
```

This defines two servers on which all Cycloid components will be installed

```
cat >> inventory <<EOF
# This IP pool contain the address of Cycloid "core" servers
[pool]
1.2.3.4
5.6.7.8

[cycloid_core:children]
pool
[cycloid_scheduler:children]
pool
[cycloid_cache:children]
pool
[smtp_server:children]
pool
[cycloid_creds:children]
pool

#[espool]
#9.8.7.6
#[elasticsearch:children]
#espool

# Note: Third-party groups are commented out because, as indicated in the HA schema,
# they should typically be managed by your cloud provider or equivalent service.
#[db]
#4.3.2.1
#[cycloid_db:children]
#db
#[cycloid_scheduler_db:children]
#db
EOF
```

Note: Ensure that cycloid\_scheduler instances allow traffic on ports `32768-60999` to communicate with each other. This ephemeral port range is used by [Concourse Web](https://concourse-ci.org/concourse-web.html#scaling) for forwarded worker connections

This defines two servers on which all Cycloid components will be installed

```
cat >> inventory <<EOF
# This IP pool contain the address of Cycloid "core" servers
[pool]
1.2.3.4
5.6.7.8

[cycloid_core:children]
pool
[cycloid_scheduler:children]
pool
[cycloid_cache:children]
pool
[smtp_server:children]
pool

#[espool]
#9.8.7.6
#[elasticsearch:children]
#espool

# Note: Third-party groups are commented out because, as indicated in the HA schema,
# they should typically be managed by your cloud provider or equivalent service.
#[db]
#4.3.2.1
#[cycloid_db:children]
#db
#[cycloid_scheduler_db:children]
#db
#[cycloid_creds:children]
#creds
EOF
```

Let's configure the environment. All available configuration variables can be found in the `defaults/main.yml` file.

* Regular install
* High Availability (HA) install
* High Availability (HA) install with external Vault

```
cat >> environments/cycloid.yml <<EOF
# Resolvable domain name from the instance and externally to use Cycloid console.
cycloid_console_dns: console.mydomain.org

# Cycloid license used for the first activation. If not defined, please enter the license manually after the setup by following https://docs.cycloid.io/onprem/overview.html#cycloid-licence
cycloid_licence: ""

# Initial Cycloid user
cycloid_initial_user:
  username: "admin"
  email: "disabled@no-email.cycloid"
  password: "Ch4ngm3pls"
  given_name: admin
  family_name: cycloid

# First Cycloid organization name
cycloid_initial_organization_name: Cycloid

# Set a random key to sign all the API JWT
cycloid_jwt_key_1: "$(< /proc/sys/kernel/random/uuid):$(< /dev/urandom tr -dc A-Za-z0-9 | head -c64)"

# Set random password for databses.
cycloid_db_password: "$(< /dev/urandom tr -dc _A-Za-z0-9- | head -c32)"
concourse_db_password: "$(< /dev/urandom tr -dc _A-Za-z0-9- | head -c32)"
cycloid_crypto_signing_key: "$(< /dev/urandom tr -dc _A-Za-z0-9- | head -c32)"
cycloid_cache_password: "$(< /dev/urandom tr -dc _A-Za-z0-9- | head -c32)"

# Defines the password for the Concourse CI user
concourse_auth_password: "$(< /dev/urandom tr -dc _A-Za-z0-9- | head -c32)"
EOF
```

As described in the On-Prem HA schema, the user must provide at least 2 external databases:

* Postgresql `17`
* Mysql `9.4`

You can use your own production databases managed by your DBA team, or leverage managed database services from a cloud provider.

The PostgreSQL database will be used by our pipeline engine, Concourse. Following our recommendations and the Concourse [prerequisites](https://concourse-ci.org/postgresql-node.html#db-prerequisites):

* Locales for the databases should be set to `US`.
* If using `pgbouncer`, ensure that `pool_mode` is configured to `session` (not transaction).

Since Cycloid uses Vault to store credentials, a storage backend must be provided. Supported backends are listed in the [Vault storage documentation](https://developer.hashicorp.com/vault/docs/configuration/storage) If using a dedicated backend is not possible, a `file` backend backed by a shared NFS filesystem can be used. One of the simplest backends to use is MySQL. Depending on the expected amount of data, the Cycloid database can be configured as follows:

```
cat >> environments/cycloid.yml <<EOF
# Resolvable domain name from the instance and externally to use Cycloid console.
cycloid_console_dns: cycloid-ha.local.tld
# Resolvable domain name used by cycloid to reach concourse web (by default 8443 port)
concourse_url: "https://cycloid-ha.local.tld"

# Cycloid license used for the first activation. If not defined, please enter the license manually after the setup by following https://docs.cycloid.io/onprem/overview.html#cycloid-licence
cycloid_licence: ""

# Cycloid initial user details
cycloid_initial_user:
  username: "admin"
  email: "disabled@no-email.cycloid"
  password: "Ch4ngm3pls"
  given_name: admin
  family_name: cycloid

# First Cycloid organization name
cycloid_initial_organization_name: Cycloid

# Set a random key to sign all the API JWT
cycloid_jwt_key_1: "$(< /proc/sys/kernel/random/uuid):$(< /dev/urandom tr -dc A-Za-z0-9 | head -c64)"

# Use local node services instead of the default first IP of the group.
vault_url: "https://{{ hostvars[inventory_hostname]['ansible_default_ipv4']['address'] }}:8200"
cycloid_cache_host: "{{ hostvars[inventory_hostname]['ansible_default_ipv4']['address'] }}"
cycloid_cache_password: "$(< /dev/urandom tr -dc _A-Za-z0-9- | head -c32)"

# Specifies the address of the SMTP server used for sending emails
# Example with local relay installed locally
#cycloid_email_smtp_svr_addr: "{{ hostvars[inventory_hostname]['ansible_default_ipv4']['address'] }}:1025"

# Define a cryptographic signing key within the Cycloid platform
cycloid_crypto_signing_key: "$(< /dev/urandom tr -dc _A-Za-z0-9- | head -c32)"

# Defines the password for the Concourse CI user
concourse_auth_password: "$(< /dev/urandom tr -dc _A-Za-z0-9- | head -c32)"

# External Mysql db information
cycloid_db_password: "SECRET"
cycloid_db_host: "IP_ADDRESS"
cycloid_db_port: 3306
cycloid_db_user: cycloid
cycloid_db_name: cycloid

# External Postgresql db information
concourse_db_password: "SECRET"
concourse_db_host:  "IP_ADDRESS"
concourse_db_user: concourse
concourse_db_port: 5432
concourse_db_name: concourse

# Override Vault config to use Mysql backend for HA
# https://developer.hashicorp.com/vault/docs/configuration/storage/mysql
# Note: This example use the same Mysql database as Cycloid one
vault_config:
  storage:
    mysql:
      address: "{{ cycloid_db_host }}:{{ cycloid_db_port }}"
      username: "{{ cycloid_db_user }}"
      password: "{{ cycloid_db_password }}"
      database: "vault"
  ui: true
  listener:
    tcp:
      address: "0.0.0.0:8200"
      tls_disable: "0"
      tls_cert_file: "/vault/config/ssl.crt"
      tls_key_file:  "/vault/config/ssl.key"
  default_lease_ttl: "168h"
  max_lease_ttl: "720h"
EOF
```

This setup is similar to **High Availability (HA) install**, but uses an external Vault server.

* Vault `>= 1.15.0`

First, ensure that the database requirements from **High Availability (HA) install** are satisfied.

The external Vault must have the following configured:

* `TLS` enabled
* `approles` authentication enabled
* A `/cycloid` mount point

Below are example commands that can be used to configure Vault for Cycloid:

**Vault - Initialize mount point and enable AppRole authentication**

```
# Create a cycloid secret mountpoint
vault secrets enable -path cycloid kv

# Enable approle authentication
vault auth enable approle
```

**Vault - Create Required Policies**

```
# Create policies for Cycloid
docker exec -e VAULT_SKIP_VERIFY=true vault vault policy write cycloid-ro -

# Create policies for Cycloid scheduler
cat << EOF | docker exec -i -e VAULT_SKIP_VERIFY=true vault vault policy write cycloid-ro -
path "cycloid/*" {
policy = "read"
}

path "auth/token/create" {
policy = "write"
}

path "auth/token/renew-self" {
policy = "write"
}
EOF

# Create policies for Cycloid
cat << EOF | docker exec -i -e VAULT_SKIP_VERIFY=true vault vault policy write cycloid -
path "cycloid/*" {
  capabilities = ["create", "read", "update", "delete", "list"]
}

path "sys/policy/cycloid/*" {
  capabilities = ["create", "read", "update", "delete", "list"]
}

path "auth/approle/role/cycloid-*" {
  capabilities = ["create", "read", "update", "delete", "list"]
}

path "auth/approle/role/" {
  capabilities = ["read", "list"]
}

path "policies" {
  capabilities = ["read", "list"]
}

path "auth/token/create" {
  capabilities = ["create"]
}

path "auth/token/renew-self" {
  capabilities = ["create"]
}
EOF
```

**Vault - Create approles for Cycloid**

```

# Create approle for cycloid
# . Create role
docker exec -e VAULT_SKIP_VERIFY=true vault vault write auth/approle/role/cycloid token_max_ttl=1h policies=cycloid token_ttl=20m
# . Get role id
docker exec -e VAULT_SKIP_VERIFY=true vault vault read auth/approle/role/cycloid/role-id -format=json

  "data": {
    "role_id": "42cbfd54-1786-e5f2-ab1d-78af660e1b9a"
  },


# . Get role secret
docker exec -e VAULT_SKIP_VERIFY=true vault vault write -f auth/approle/role/cycloid/secret-id -format=json

  "data": {
    "secret_id": "39bb1383-a753-aeac-7008-73bce0e459d3",
    "secret_id_accessor": "6c1b4bd6-5993-4439-0858-e7ec4e562aaf"
  },


# Create approle for cycloid scheduler
docker exec -e VAULT_SKIP_VERIFY=true vault vault write auth/approle/role/cycloid-ro period=30m token_max_ttl=0m policies=cycloid-ro token_ttl=30m
docker exec -e VAULT_SKIP_VERIFY=true vault vault read auth/approle/role/cycloid-ro/role-id -format=json
docker exec -e VAULT_SKIP_VERIFY=true vault vault write -f auth/approle/role/cycloid-ro/secret-id -format=json
```

**Cycloid - Configure onprem environment**

```
cat >> environments/cycloid.yml <<EOF
# Resolvable domain name from the instance and externally to use Cycloid console.
cycloid_console_dns: cycloid-ha.local.tld
# Resolvable domain name used by cycloid to reach concourse web (by default 8443 port)
concourse_url: "https://cycloid-ha.local.tld"

# Cycloid license used for the first activation. If not defined, please enter the license manually after the setup by following https://docs.cycloid.io/onprem/overview.html#cycloid-licence
cycloid_licence: ""

# Cycloid initial user details
cycloid_initial_user:
  username: "admin"
  email: "disabled@no-email.cycloid"
  password: "Ch4ngm3pls"
  given_name: admin
  family_name: cycloid

# First Cycloid organization name
cycloid_initial_organization_name: Cycloid

# Set a random key to sign all the API JWT
cycloid_jwt_key_1: "$(< /proc/sys/kernel/random/uuid):$(< /dev/urandom tr -dc A-Za-z0-9 | head -c64)"

# Force to use locally installed service instead of the default first IP of the group.
cycloid_cache_host: "{{ hostvars[inventory_hostname]['ansible_default_ipv4']['address'] }}"
cycloid_cache_password: "$(< /dev/urandom tr -dc _A-Za-z0-9- | head -c32)"

# Note: In case vault is installed locally
#vault_url: "https://{{ hostvars[inventory_hostname]['ansible_default_ipv4']['address'] }}:8200"

# In case of email service installed locally
#cycloid_email_smtp_svr_addr: "{{ hostvars[inventory_hostname]['ansible_default_ipv4']['address'] }}:1025"

# Define a cryptographic signing key within the Cycloid platform
cycloid_crypto_signing_key: "$(< /dev/urandom tr -dc _A-Za-z0-9- | head -c32)"

# Defines the password for the Concourse CI user
concourse_auth_password: "$(< /dev/urandom tr -dc _A-Za-z0-9- | head -c32)"

# External vault url
#vault_url: "https://IP_ADDRESS:8200"
vault_approle_cycloid_role_id: "SECRET"
vault_approle_cycloid_secret_id: "SECRET"
vault_approle_cycloid_scheduler_role_id: "SECRET"
vault_approle_cycloid_scheduler_secret_id: "SECRET"

# External Mysql db information
cycloid_db_password: "SECRET"
cycloid_db_host: "IP_ADDRESS"
cycloid_db_port: 3306
cycloid_db_user: cycloid
cycloid_db_name: cycloid

# External Postgresql db information
concourse_db_password: "SECRET"
concourse_db_host:  "IP_ADDRESS"
concourse_db_user: concourse
concourse_db_port: 5432
concourse_db_name: concourse
EOF
```

cycloid\_initial\_organization

In an On-Prem setup, the first organization created is special and can be considered the **admin organization**. Internally, we call it the `root organization`. All other organizations created will be children of this root organization.

Since a member of an organization has access to all its child organizations, a member of the root organization will have access to **all organizations**.

Run Ansible to set up the Cycloid core (use `-c local` if running Ansible directly on the server)

```
ansible-playbook -u admin -b -i inventory playbook.yml
```

This playbook will create a local `datas/vault.secret` file at the end of the setup. Make sure to **backup and secure it**, as it contains the root token for Vault.

Important

If the server is restarted, you may need to [unseal Vault](https://developer.hashicorp.com/vault/docs/concepts/seal).

To simplify the unseal process, the `datas/vault.secret` file created during setup can be used with the `vault_unseal.yml` playbook as follows:

```
ansible-playbook -u admin -b -i inventory vault_unseal.yml
```

**Uninstall**

If the installation fails and you need to clean your servers before running it again, you can uninstall by running `playbook.yml` with `-e uninstall=True`

```
ansible-playbook -u admin -b -i inventory -e uninstall=True playbook.yml
```

### Cycloid worker installation[​](#cycloid-worker-installation "Direct link to Cycloid worker installation")

![Schema](/assets/images/onprem-workers-cc103401cbb7f3a850d4d19edd960b93.png) A Cycloid worker requires two types of network access to the Cycloid scheduler:

* **Scheduler API**: HTTPS URL specified under `concourse_url` during core installation.

* **Scheduler (SSH)**: Network access using the SSH protocol:

  <!-- -->

  * **Scheduler host**: Hostname, IP, or DNS specified under `concourse_tsa_host` during core installation.
  * **Scheduler port**: Port number specified under `concourse_tsa_port` during core installation.
  * **Scheduler TSA public key**: Public SSH key specified under `concourse_tsa_public_key` during core installation.

Using a different network between worker and scheduler

If your worker is not on the same private network as the scheduler, ensure that a public or otherwise routable IP address is configured. This allows the worker to properly connect to the scheduler.

In Cycloid, there are two types of workers:

* **Global**: Often used on-premise. Sets up a pool of workers for all Cycloid users, usable across all organizations.
* **Organization-scoped**: Used in our SaaS version. Each organization connects its own worker to run pipelines. Installation details are available in our official [product documentation](/reference/ci-cd-pipelines/concepts/workers/.md).

#### Global worker with Ansible[​](#global-worker-with-ansible "Direct link to Global worker with Ansible")

Add a new host section for workers in the Ansible inventory

```
echo -e "[cycloid_worker]\n4.3.2.1" >> inventory
```

Install required Ansible role to setup Cycloid worker

```
ansible-galaxy role install -r worker-requirements.yml -p roles -v --force
```

Use the server IP from the previous Cycloid core installation step to configure the workers

```
export SCHEDULER_API_ADDRESS=1.2.3.4
export VERSION=$(curl -sL "${SCHEDULER_API_ADDRESS}:8080/api/v1/info" | jq -r '.version')
```

Configure the Ansible playbook to set up Cycloid workers

```
cat >> environments/cycloid.yml <<EOF
# Cycloid workers section
concourse_worker: yes
concourse_worker_name: "\$(hostname)"
concourse_service_enabled: yes
# concourse_worker_env:
    # HTTP proxy configuration. Make sure to set the right url's into no_proxy
    # http_proxy: http://mydomain:8080
    # https_proxy: http://mydomain:8080
    # extra_no_proxy:
    #  - miniphost
    #  - elasticsearchhost
concourse_worker_options: |
  --ephemeral \\
  --baggageclaim-log-level=error \\
  --baggageclaim-volumes={{ concourse_work_dir }}/baggageclaim_volumes \\
  --baggageclaim-driver=overlay 2>&1 | tee -a /var/log/concourse-worker.log ; exit \${PIPESTATUS[0]}

concourse_install_dir: /var/lib/concourse
concourse_work_dir: /var/lib/concourse/datas

concourse_version: "${VERSION}"
concourse_tsa_port: "2222"
concourse_tsa_host: "$SCHEDULER_API_ADDRESS"
concourse_tsa_public_key: "{{lookup('file', 'keys/id_rsa.pub')}}"
concourse_tsa_worker_key: "{{lookup('file', 'keys/id_rsa')}}"
EOF
```

Then run the playbook to set up Cycloid workers

```
ansible-playbook -u admin -b -i inventory worker.yml
```

#### Global Worker with Cloud Provider Deployment Tool[​](#global-worker-with-cloud-provider-deployment-tool "Direct link to Global Worker with Cloud Provider Deployment Tool")

As described above, **Organization-scoped** workers can be deployed using our dedicated [product documentation](/reference/ci-cd-pipelines/concepts/workers/.md). This approach provides a convenient way to deploy workers, especially on major cloud providers, using their automated deployment tools, such as AWS CloudFormation, GCP Deployment Manager, and others.

However, it is also possible to leverage these cloud provider-specific deployment tools to create a **global worker**.

You will need to gather the following information:

* **Worker private key (base64 encoded)** The private SSH key for workers, provided under the Ansible variable `concourse_tsa_worker_key` (or `concourse.secrets.workerKey` for Kubernetes).

warning

Worker private key has to be provided in base64. If the private key is not in base64 format, for example in Ansible setup, you can encode it manually using the command below:

```
cat keys/id_rsa | base64 -w0
```

As a platform administrator, connect to a Cycloid organization and follow the steps to deploy a scoped worker as described in the [product documentation](/reference/ci-cd-pipelines/concepts/workers/.md).

Then, replace the following fields:

* AWS
* Azure
* GCP

- Cycloid CI team ID: `global`
- Cycloid CI worker private key: `Base64 key from above`

* Team ID: `global`
* Worker Key: `Base64 key from above`

- CYCLOID\_TEAM: `global`
- CYCLOID\_WORKER\_KEY: `Base64 key from above`

## Cycloid Licence[​](#cycloid-licence "Direct link to Cycloid Licence")

Cycloid products require a license to operate. Licenses have a maximum number of users and an expiration date. For more information, please contact Cycloid.

Licenses can be activated or renewed from the **root organization** view by clicking the top-left icon.

If no license has been activated, you should see: ![licence-inactive](/assets/images/licence-inactive-1104c067d56ff1aec9941bfb0acb3eae.png)

To activate or renew a license, click the `Add licence` button and paste your license key. It should look like this: ![licence-paste](/assets/images/licence-renew-57c208deac6945b24282a1e28aedf6b0.png)

After clicking `Add licence`, your view should change to: ![licence-active](/assets/images/licence-active-cb5725fe41ffa4b161a9f57a4bd0e1cc.png)

## Upgrade[​](#upgrade "Direct link to Upgrade")

### Cycloid ansible playbooks[​](#cycloid-ansible-playbooks "Direct link to Cycloid ansible playbooks")

Retrieve the latest playbooks from Git:

```
cd ansible-cycloid-onprem
git pull
cd ../cycloid-onprem
cp -a ../ansible-cycloid-onprem/playbooks/* .
```

Activate your Python `virtualenv`:

```
source venv/bin/activate
export ANSIBLE_PYTHON_INTERPRETER=/usr/bin/python3
python3 -m pip install -U -r pip-requirements.txt
```

Load the Access Key provided by Cycloid:

```
export SCW_SECRET_KEY=SCW...
export SCW_ACCESS_KEY=...
```

### Cycloid core upgrade[​](#cycloid-core-upgrade "Direct link to Cycloid core upgrade")

Upgrade the required Ansible roles to set up the Cycloid core:

```
ansible-galaxy role install -r requirements.yml -p roles -v --force
ansible-galaxy collection install -r requirements.yml -p collections -v --force
```

Run Ansible to upgrade the Cycloid core (use `-c local` if running Ansible directly on the server):

```
ansible-playbook -u admin -b -i inventory playbook.yml
```

### Cycloid worker upgrade[​](#cycloid-worker-upgrade "Direct link to Cycloid worker upgrade")

Update the Ansible roles required for Cycloid worker setup:

```
ansible-galaxy role install -r worker-requirements.yml -p roles -v --force
```

Using the scheduler API IP address from the previous Cycloid core installation, configure the workers to use the matching Concourse version:

```
export SCHEDULER_API_ADDRESS=1.2.3.4
export VERSION=$(curl -sL "${SCHEDULER_API_ADDRESS}:8080/api/v1/info" | jq -r '.version')

sed -i "s/concourse_version:.*/concourse_version: \"${VERSION}\"/" environments/cycloid.yml
```

Run the Ansible playbook to upgrade Cycloid workers:

```
ansible-playbook -u admin -b -i inventory worker.yml
```


---

# Getting started with Cycloid

Welcome to the **Cycloid Sustainable Platform Engineering** Getting Started Guide! This guide will help you quickly set up and navigate your everyday tasks efficiently.

Cycloid is designed for a diverse range of users such as [end users](/cookbook/getting-started/end-users/.md), [devops teams](/cookbook/getting-started/devops-teams/.md) and [platform teams](/cookbook/getting-started/platform-teams/.md).

We have created dedicated sections for each user profile to cater for their specific needs.

Concepts

Concepts are great to understand how Cycloid works under the hood. Make sure to take advantage of them.

Before going further, you may want to have an overview of **Cycloid Sustainable Platform Engineering**. Here is a demonstration video of the platform and its main features.

[YouTube video player](https://www.youtube.com/embed/7N3NpbRclDk)


---

# Cycloid for DevOps teams

## Audience[​](#audience "Direct link to Audience")

This section is for DevOps teams who create and maintain Cycloid stacks for end users to use from the service catalog.

## Objectives[​](#objectives "Direct link to Objectives")

At the end of this section, you will master building and managing Cycloid Stacks in the service catalogs available to the end users.

Concepts

A service catalog is a collection of Stacks used by the end users to create new Projects and Environments. For more details on these essential concepts, please go to the [reference manual](/reference/projects/.md).

A Stack typically contains:

1. Some automation technologies such as Terraform, Ansible, Helm charts, etc.
2. A CI/CD pipeline to execute the automation
3. A StackForms definition file (`.forms.yml`) to design user-friendly web forms
4. A Stack metadata file (`.cycloid.yml`) to describe the Stack

As a DevOps team member, you will create and maintain the Stacks files that will be version-controlled in your Git repository. Your Stacks will typically reside in different folders at the root of your Git repository. Cycloid will crawl your Git repository up to one folder depth maximum to build the service catalogs available to end users via the Cycloid self-service portal.

## Prerequisites[​](#prerequisites "Direct link to Prerequisites")

* A personal Cycloid account with appropriate permissions is required. Typically the user may join the Cycloid organization with at least the Project Manager role.
* Read access to your Git repositories containing your Cycloid stacks is required.
* Read and write access to your Git repositories containing your configuration is required.
* Make sure your Git repository is configured in the `Catalog repositories` tab from the `Stacks` page in your Cycloid organization.

Check the [config and catalog repository section](/reference/config-and-catalog-repository/.md) for more details.

info

If your Git repository is not configured, click the `Add catalog repository` button in the Catalog repositories tab from the Stacks page in your Cycloid organization.

If you don't have permission to do this action, please contact your Cycloid platform team to configure it.


---

# Ways to create a Stack

As a DevOps team member, you may be interested to learn how to create and customize [Cycloid Stacks](/reference/stacks/.md). Let's first create a new Stack in your service catalog git repository.

There are mainly three ways to create a Stack:

1. [From a blueprint](/cookbook/getting-started/devops-teams/stack-creation/blueprint.md)
2. [From an existing infrastructure](/cookbook/getting-started/devops-teams/stack-creation/import.md)
3. [From community Stacks](/cookbook/getting-started/devops-teams/stack-creation/community.md)


---

# From a stack blueprint

## Create a stack from a blueprint[​](#create-a-stack-from-a-blueprint "Direct link to Create a stack from a blueprint")

In this section, we are going to push a new stack to your service catalog Git repository using a stack blueprint.

Concepts

Stack blueprints are models of stacks that include your organization's best practices and security rules. It can be leveraged to generate new stacks using a powerful templating language.

Stack blueprints are stored in Git repositories, the same way you do with your stacks. To turn a stack into a blueprint, just add a `template: true` attribute in the `.cycloid.yml` as well as some templating. Read more on how to create stack blueprints [here](/reference/stack-blueprint/.md).

Let's create a new Stack from a blueprint and push it into your service catalog Git repository.

1. Go to **Stacks** on the left-hand side menu
2. Click on the **Create a new Stack** button and then on **Create from blueprint**
3. Select the Stack blueprint you want to use, depending on your automation technology and cloud provider
4. Give a name to your new Stack
5. Select a catalog repository where your new Stack will be pushed

That’s it! Your Git catalog repository now contains a new Stack. You can have a look at the files in your Git repository and start to [customize your new stack](/cookbook/getting-started/devops-teams/stack-customization/.md).

tip

If you don't have any stack blueprint yet, you can get started by adding `https://github.com/cycloid-community-catalog/onboarding-templates.git` as an additional Catalog repository. Later on, you may want to create your own stack blueprints as well!


---

# From community catalog

## Create a stack from the Cycloid community catalog[​](#create-a-stack-from-the-cycloid-community-catalog "Direct link to Create a stack from the Cycloid community catalog")

If you want to create your stack from scratch, just create the files in your Git repository. But to get started quickly and get some inspiration, you can copy some files from our public Cycloid community catalog.

tip

Some Cycloid public stacks are available here: <https://github.com/cycloid-community-catalog/onboarding-stacks>

This will generate Terraform IaC and push a new Stack in your service catalog Git repository.

1. Clone the Cycloid community catalog
2. Copy the files to your stack folder and customize them according to your use case
3. Commit and push the changes to your Git repository
4. Refresh the service catalog from the `Refresh` button in the `Catalog repositories` tab on the `Stacks` page

That’s it! Your service catalog now contains a new Stack available to your users.


---

# From existing infrastructure

## Create a stack from an existing infrastructure[​](#create-a-stack-from-an-existing-infrastructure "Direct link to Create a stack from an existing infrastructure")

In this section, we are going to generate Terraform infrastructure-as-code from an already deployed infrastructure and push a stack with this infrastructure-as-code to your service catalog Git repository.

Concepts

Infra Import uses [TerraCognita](https://github.com/cycloidio/terracognita), an Open Source Software created and maintained by Cycloid.

It creates the Terraform HCL as well as the corresponding Terraform state file from a workload deployed on AWS, Azure, GCP, or VMware. The Terraform HCL would be included in the newly created Cycloid Stack pushed in your service catalog Git repository, and the associated Terraform state file would be typically stored in a cloud storage bucket.

Prerequisites

Before starting this process, you'll need a credential to access your cloud account (read-only on the imported resources), because Infra Import will generate the infrastructure-as-code by reading your deployed infrastructure.

If you already have permission to create a Cycloid Credential, please refer to the [Reference guide](/reference/credentials/quickstart.md), otherwise ask your Platform Team to create it for you.

Let's now create a new Stack with the infrastructure-as-code describing your cloud resources and push it into your service catalog Git repository.

1. Go to **Stacks** on the left-hand side menu
2. Click on the **Create a new Stack** button and then on **Import your infrastructure**
3. Click on the **Create Stack** button
4. Configure your cloud provider
5. Select the resource types to import from the dropdown menu
6. Select the resource attributes that will be available via StackForms when creating a project with this stack
7. Give a name to your new Stack
8. Select a catalog repository where your new Stack will be pushed

That’s it! Your Git catalog repository now contains a new Stack with the generated infrastructure-as-code for your cloud resources. You can look at the files in your Git repository and start customizing your new stack.


---

# Customize your Stacks

After creating a Stack, you will want to adapt it to your specific use case. The process depends on which automation technologies you are using.

In the next sections, we will customize a Stack [created from a blueprint](/cookbook/getting-started/devops-teams/stack-creation/blueprint.md), using common technologies such as:

1. [Terraform](/cookbook/getting-started/devops-teams/stack-customization/terraform.md)
2. [Ansible](/cookbook/getting-started/devops-teams/stack-customization/ansible.md)
3. [Helm](/cookbook/getting-started/devops-teams/stack-customization/helm.md).

info

Cycloid is very much agnostic to automation technologies, so these are only common examples.

To use other automation technologies in your Stacks, you may want to go to the [reference manual](/reference/stacks/.md).


---

# Using Ansible

After creating a Stack [from a blueprint](/cookbook/getting-started/devops-teams/stack-creation/blueprint.md) using Ansible, we'll explore how to customize it, including changing the Ansible playbook to your use case and exposing the variables via StackForms.

1. Clone your Stack from your service catalog Git repository.
2. Replace the Ansible playbook from the blueprint with yours. It is usually located in a YAML file in the `ansible` folder. As an example, let's include a simple restart of a service. Its name is passed as an Ansible extra variable named `hosts_service`.

ansible/site.yml

```
---
- name: Operations
  hosts: '{{ hosts_inventory }}'
  become: yes

  tasks:
  - name: Reboot All
    reboot:
      reboot_timeout: 300
    when: hosts_reboot|bool == True

  - name: Service to Restart
    service:
      name: '{{ hosts_service }}'
      state: restarted
    when: (hosts_service is defined) and (hosts_service|length > 0)
[...]
```

3. Make sure you have an `ansible/group_vars` folder (it can be empty). Cycloid will use it to provide the pipeline and StackForms variables to your Ansible playbook (in our example this would be the `hosts_inventory` and the `hosts_service` variables).
4. Review the `pipeline.yml` file in the `pipeline` folder and adapt it as required. It builds a dynamic inventory for your cloud provider and it also gives variables expected by your Ansible playbook.

* AWS
* Azure
* GCP

Ansible task for AWS in pipeline/pipeline.yml

```
[...]
      - task: run-ansible
        config:
          platform: linux
          image_resource:
            type: registry-image
            source:
              repository: cycloid/cycloid-toolkit
              tag: ((ansible_version))
          run:
            path: /usr/bin/ansible-runner
          caches:
            - path: ansible-playbook/roles
          inputs:
          - name: merged-stack
            path: ansible-playbook
        params:
          #+ Parameters of ansible-runner script. Can be found here: https://github.com/cycloidio/docker-cycloid-toolkit#ansible-runner
          SSH_PRIVATE_KEY: ((hosts_private_key))
          ANSIBLE_REMOTE_USER: ((hosts_username))

          #+ AWS Dynamic Inventory
          EC2_VPC_DESTINATION_VARIABLE: ip_address
          AWS_ACCESS_KEY_ID: ((aws_access_key))
          AWS_SECRET_ACCESS_KEY: ((aws_secret_key))
          AWS_DEFAULT_REGION: ((aws_region))

          ANSIBLE_PLAYBOOK_PATH: ansible-playbook
          ANSIBLE_PLAYBOOK_NAME: site.yml
          ANSIBLE_EXTRA_VARS:
            cai_host: ((cai_host))
            hosts_inventory: ((hosts_inventory))
            hosts_service: ((hosts_service))
            hosts_reboot: ((hosts_reboot))
            hosts_package: ((hosts_package))
            hosts_user: ((hosts_user))
[...]
```

Ansible task for Azure in pipeline/pipeline.yml

```
[...]
      - task: run-ansible
        config:
          platform: linux
          image_resource:
            type: registry-image
            source:
              repository: cycloid/cycloid-toolkit
              tag: ((ansible_version))
          run:
            path: /usr/bin/ansible-runner
          caches:
            - path: ansible-playbook/roles
          inputs:
          - name: merged-stack
            path: ansible-playbook
        params:
          #+ Parameters of ansible-runner script. Can be found here: https://github.com/cycloidio/docker-cycloid-toolkit#ansible-runner
          SSH_PRIVATE_KEY: ((hosts_private_key))
          ANSIBLE_REMOTE_USER: ((hosts_username))

          #+ Azure Dynamic Inventory
          AZURE_USE_PRIVATE_IP: False # Force to connect to public IP because we don't use a bastion in this stack
          AZURE_SUBSCRIPTION_ID: ((azure_subscription_id))
          AZURE_TENANT_ID: ((azure_tenant_id))
          AZURE_TENANT: ((azure_tenant_id))
          AZURE_CLIENT_ID: ((azure_client_id))
          AZURE_SECRET: ((azure_client_secret))

          ANSIBLE_PLAYBOOK_PATH: ansible-playbook
          ANSIBLE_PLAYBOOK_NAME: site.yml
          ANSIBLE_EXTRA_VARS:
            cai_host: ((cai_host))
            hosts_inventory: ((hosts_inventory))
            hosts_service: ((hosts_service))
            hosts_reboot: ((hosts_reboot))
            hosts_package: ((hosts_package))
            hosts_user: ((hosts_user))
[...]
```

Ansible task for GCP in pipeline/pipeline.yml

```
[...]
      - task: run-ansible
        config:
          platform: linux
          image_resource:
            type: registry-image
            source:
              repository: cycloid/cycloid-toolkit
              tag: ((ansible_version))
          run:
            path: /usr/bin/ansible-runner
          caches:
            - path: ansible-playbook/roles
          inputs:
          - name: merged-stack
            path: ansible-playbook
        params:
          #+ Parameters of ansible-runner script. Can be found here: https://github.com/cycloidio/docker-cycloid-toolkit#ansible-runner
          SSH_PRIVATE_KEY: ((hosts_private_key))
          ANSIBLE_REMOTE_USER: ((hosts_username))

          #+ GCP Dynamic Inventory
          GCP_USE_PRIVATE_IP: False # Force to connect to public IP because we don't use a bastion in this stack
          GCP_SERVICE_ACCOUNT_CONTENTS: ((gcp_credentials_json))

          ANSIBLE_PLAYBOOK_PATH: ansible-playbook
          ANSIBLE_PLAYBOOK_NAME: site.yml
          ANSIBLE_EXTRA_VARS:
            cai_host: ((cai_host))
            hosts_inventory: ((hosts_inventory))
            hosts_service: ((hosts_service))
            hosts_reboot: ((hosts_reboot))
            hosts_package: ((hosts_package))
            hosts_user: ((hosts_user))
[...]
```

tip

The Cycloid ansible-runner script parameters are described here: <https://github.com/cycloidio/docker-cycloid-toolkit#ansible-runner>

Note the `ANSIBLE_EXTRA_VARS` attribute where we provide pipeline variables to the Ansible playbook as group variables. Add more variables here as needed.

6. Review the `variables.sample.yml` file in the `pipeline` folder and make sure at least the above variables in double parenthesis are declared. Typically, `pipeline/variables.sample.yml` should include this:

* AWS
* Azure
* GCP

pipeline/variables.sample.yml

```
[...]
#. aws_access_key (required): ((aws.access_key))
#+ AWS access key for Terraform.
aws_access_key: ((aws.access_key))

#. aws_secret_key (required): ((aws.secret_key))
#+ AWS secret key for Terraform.
aws_secret_key: ((aws.secret_key))

#. aws_default_region (required): eu-west-1
#+ AWS region to build the Ansible dynamic inventory.
aws_region: eu-west-1

#. hosts_username (required): admin
#+ The username to connect to via SSH to execute the Ansible playbook.
hosts_username: admin

#. hosts_private_key (required): ((key_pair.private_key))
#+ The private SSH key to connect via SSH to execute the Ansible playbook.
hosts_private_key: ((key_pair.private_key))
[...]
```

pipeline/variables.sample.yml

```
[...]
#. azure_subscription_id (required): ((azure.subscription_id))
#+ Azure subscription ID to build the Ansible dynamic inventory.
azure_subscription_id: ((azure.subscription_id))

#. azure_tenant_id (required): ((azure.tenant_id))
#+ Azure tenant ID to build the Ansible dynamic inventory.
azure_tenant_id: ((azure.tenant_id))

#. azure_client_id (required): ((azure.client_id))
#+ Azure client ID to build the Ansible dynamic inventory.
azure_client_id: ((azure.client_id))

#. azure_client_secret (required): ((azure.client_secret))
#+ Azure client secret to build the Ansible dynamic inventory.
azure_client_secret: ((azure.client_secret))

#. hosts_username (required): admin
#+ The username to connect to via SSH to execute the Ansible playbook.
hosts_username: admin

#. hosts_private_key (required): ((key_pair.private_key))
#+ The private SSH key to connect via SSH to execute the Ansible playbook.
hosts_private_key: ((key_pair.private_key))
[...]
```

pipeline/variables.sample.yml

```
[...]
#. gcp_credentials_json (required): ((gcp.json_key))
#+ Google Cloud Platform JSON credentials to build the Ansible dynamic inventory.
gcp_credentials_json: ((gcp.json_key))

#. hosts_username (required): admin
#+ The username to connect to via SSH to execute the Ansible playbook.
hosts_username: admin

#. hosts_private_key (required): ((key_pair.private_key))
#+ The private SSH key to connect via SSH to execute the Ansible playbook.
hosts_private_key: ((key_pair.private_key))
[...]
```

tip

`((my_cred_name))` refers to a credential with a canonical name `my_cred_name`. Please visit Security ➔ Credentials in the Cycloid console to manage your credentials. it will be the default value, unless the value is overridden by StackForms.

`($ .component $), ($ .env $)` and `($ .project $)` are Cycloid [special variables](/reference/stacks/concepts/templating.md#special-variables) replaced at pipeline instantiation. These variables come from the project and environment canonical names as entered by the end-user in the Cycloid console.

`($ .org $)` would be replaced by the organization's canonical name where the project has been created.

7. Edit the `.forms.yml` file in the root folder, and adapt the pipeline and terraform variables accordingly. For more information on how to use StackForms, please go to the dedicated [StackForms Cookbook section](/cookbook/getting-started/devops-teams/stackforms/.md) or to the [StackForms Reference manual](/reference/stackforms/.md).

* AWS
* Azure
* GCP

.forms.yml

```
version: "2"
use_cases:
- name: default
  sections:
  - name: Dynamic Inventory Configuration
    groups:
    - name: AWS Access Configuration
      technologies: [pipeline]
      vars:
      - name: "AWS access key"
        description: "AWS access key for Terraform."
        key: aws_access_key
        widget: cy_cred
        widget_config:
          display_keys: true
          cred_types:
            - aws
        type: string
        default: ""
        required: true
      - name: "AWS secret key"
        description: "AWS secret key for Terraform."
        key: aws_secret_key
        widget: cy_cred
        widget_config:
          display_keys: true
          cred_types:
            - aws
        type: string
        default: ""
        required: true
      - name: "AWS region"
        description: "AWS region where targeted EC2 are deployed."
        key: aws_region
        type: string
        widget: auto_complete
        values_ref: https://cycloid-demo-stackforms-values.s3.eu-west-1.amazonaws.com/aws-regions.json
        default: eu-west-1
        required: true

    - name: Operations
      technologies: [ansible]
      vars:
      - name: "Service to Restart"
        description: "A single service to restart on a Linux machine. Supported init systems include BSD init, OpenRC, SysV, Solaris SMF, systemd, upstart."
        key: hosts_service
        type: string
        widget: simple_text
```

.forms.yml

```
version: "2"
use_cases:
- name: default
  sections:
  - name: Dynamic Inventory Configuration
    groups:
    - name: Azure Access Configuration
      technologies: [pipeline]
      vars:
      - name: "Azure subscription ID"
        description: "Azure subscription ID for Terraform."
        key: azure_subscription_id
        widget: cy_cred
        type: string
        default: ""
        required: true
      - name: "Azure tenant ID"
        description: "Azure tenant ID for Terraform."
        key: azure_tenant_id
        widget: cy_cred
        type: string
        default: ""
        required: true
      - name: "Azure client ID"
        description: "Azure client ID for Terraform."
        key: azure_client_id
        widget: cy_cred
        type: string
        default: ""
        required: true
      - name: "Azure client secret"
        description: "Azure client secret for Terraform."
        key: azure_client_secret
        widget: cy_cred
        type: string
        default: ""
        required: true

    - name: Operations
      technologies: [ansible]
      vars:
      - name: "Service to Restart"
        description: "A single service to restart on a Linux machine. Supported init systems include BSD init, OpenRC, SysV, Solaris SMF, systemd, upstart."
        key: hosts_service
        type: string
        widget: simple_text
```

.forms.yml

```
version: "2"
use_cases:
- name: default
  sections:
  - name: Dynamic Inventory Configuration
    groups:
    - name: GCP Access Configuration
      technologies: [pipeline]
      vars:
      - name: "GCP credentials"
        description: "Google Cloud Platform JSON credentials to use for Terraform."
        key: gcp_credentials_json
        widget: cy_cred
        widget_config:
          display_keys: true
          cred_types:
            - gcp
        type: string
        default: "((gcp.json_key))"
        required: true

    - name: Operations
      technologies: [ansible]
      vars:
      - name: "Service to Restart"
        description: "A single service to restart on a Linux machine. Supported init systems include BSD init, OpenRC, SysV, Solaris SMF, systemd, upstart."
        key: hosts_service
        type: string
        widget: simple_text
```

tip

Note the `technologies` attribute. When set to `pipeline`, the underneath variables will override pipeline variable values in `pipeline/variables.sample.yml`. And when set to `ansible`, the values will be injected as group variables in your Ansible playbook.

8. Finally, you may want to edit the `.cycloid.yml` file to change the stack metadata displayed to end-users on the Cycloid portal.
9. Commit and push the changes to your Git repository.
10. Refresh the service catalog from the `Refresh` button in the `Catalog repositories` tab on the `Stacks` page

Congratulations ! You can now test your Stack, as an end-user would do by [creating a project](/cookbook/getting-started/end-users/deploy.md).


---

# Using Helm charts

After creating a Stack [from a blueprint](/cookbook/getting-started/devops-teams/stack-creation/blueprint.md) using Helm, we'll explore how to customize it, including exposing the Helm charts values via StackForms. In this example, we will run the Helm chart using Terraform, so you can also add cloud infrastructure that may not be in a Kubernetes cluster, such as a managed database.

1. Clone your Stack from your service catalog Git repository.
2. Edit the `helm.tf` file in the terraform module folder and point to the chart you want to use. Add the chart values you want to override as well. In this example, we use a Sonatype Helm chart to deploy a Nexus Repository.

helm.tf

```
resource "helm_release" "nexus" {
  name       = "nexus"
  repository = "https://sonatype.github.io/helm3-charts"
  chart      = "nexus-repository-manager"

  set {
    name  = "nexus.nexusPort"
    value = "${var.nexus_port}"
  }

  set {
    name  = "persistence.storageSize"
    value = "${var.vm_disk_size}Gi"
  }

  set {
    name  = "service.type"
    value = "LoadBalancer"
  }
}
```

tip

In this example, we are providing Terraform variables to `nexus.nexusPort` and `persistence.storageSize` chart values and we are setting `service.type` chart value to `LoadBalancer`.

Remember to add these Terraform variables to your `variables.tf` file in your Terraform module.

3. Edit the `main.tf.sample` file in the `terraform` folder to call the helm chart module accordingly. You will need to pass the Helm chart values to your Terraform module. Please note: some module variable values may be overwritten by StackForms, depending on the `.forms.yml` definition. Because this file is processed by Cycloid to inject StackForms variable values and stored in the config Git repository to keep track of each deployment desired configuration, **please do not add anything else than one or several module calls** in the `main.tf.sample` file. A typical module call looks like this:

terraform/main.tf.sample

```
module "nexus" {
  #####################################
  # Do not modify the following lines #
  source   = "./module-nexus"
  cy_org       = var.cy_org
  cy_project   = var.cy_project
  cy_env       = var.cy_env
  cy_component = var.cy_component
  #####################################

  #. vm_disk_size: 20
  #+ Disk size for the Nexus Repository (Go)
  vm_disk_size = "Value injected by StackForms"

  #. nexus_port: 8081
  #+ Port where Nexus Repository service is exposed
  nexus_port = "Value injected by StackForms"
}
```

tip

Please note: the invalid value `"Value injected by StackForms"`. This is to illustrate that the Terraform variable values will be injected by StackForms according to the end-users wishes.

4. Review the `variables.sample.yml` file in the `pipeline` folder and make sure that, at least, the `kubeconfig_content` variable is declared. Typically, it should look like this:

pipeline/variables.sample.yml

```
#. kubeconfig_content (required): "((custom_($ .org $)-($ .project $)-($ .env $)-kubeconfig.kubeconfig))"
#+ Kubeconfig content from Cycloid vault.
kubeconfig_content: "((custom_($ .org $)-($ .project $)-($ .env $)-kubeconfig.kubeconfig))"
```

tip

`((my_cred_name))` refers to a credential with a canonical name `my_cred_name`. Please visit Security ➔ Credentials in the Cycloid console to manage your credentials. This is the default value unless the value is overridden by StackForms.

5. Edit the `.forms.yml` file in the root folder, and adapt the pipeline and terraform variables accordingly. For more information on how to use StackForms, please go to the dedicated [StackForms Cookbook section](/cookbook/getting-started/devops-teams/stackforms/.md) or to the [StackForms Reference manual](/reference/stackforms/.md).

.forms.yml

```
---
version: "2"
use_cases:
- name: 'default'
  sections:
  - name: Nexus Repository
    groups:
    - name: Kubernetes Cluster
      technologies: [pipeline]
      vars:
      - name: "Kubeconfig"
        description: "Kubeconfig to access your K8s cluster. Please create it as a custom credential in Cycloid Credentials module beforehand."
        key: kubeconfig_content
        widget: cy_cred
        widget_config:
          display_keys: true
          cred_types:
            - custom
        type: string
        default: ""
        required: true
    - name: Pod specifications
      technologies: [terraform]
      vars:
      - name: "Disk size"
        unit: Go
        description: "Disk size for the Nexus Repository."
        key: vm_disk_size
        widget: slider_range
        type: integer
        default: 20
        values:
            - 10
            - 250
        required: true
    - name: Application Configuration
      technologies: [terraform]
      vars:
      - name: "Port"
        description: "Port where Nexus Repository service is exposed."
        key: nexus_port
        widget: simple_text
        type: string
        default: "8081"
        required: true
```

tip

Note the `technologies` attribute. When set to `pipeline`, the underneath variables will override pipeline variable values in `pipeline/variables.sample.yml` and when set to `terraform`, the values will be injected in the module variables as called in the `terraform/main.tf.sample` file.

6. Finally, you need to to edit the `.cycloid.yml` file to change the stack metadata displayed to end-users on the Cycloid portal.
7. Commit and push the changes to your Git repository.
8. Refresh the service catalog from the `Refresh` button in the `Catalog repositories` tab from the `Stacks` page

Congratulations ! You can now test your Stack as a end-user would do by [creating a project](/cookbook/getting-started/end-users/deploy.md).


---

# Using Terraform

After creating a Stack [from a blueprint](/cookbook/getting-started/devops-teams/stack-creation/blueprint.md) using Terraform, we'll explore how to customize it, including changing the Terraform modules to your use case and exposing the variables via StackForms.

1. Clone your Stack from your service catalog Git repository.
2. Replace the Terraform module(s) from the blueprint with yours. They are usually located in subfolders of the `terraform` folder.
3. Edit the `main.tf` (or `main.tf.sample`) file in the `terraform` folder to call your modules accordingly. You will need to pass the required variables to your Terraform modules. Please note that some module variable values may be overwritten by StackForms, depending on the `.forms.yml` definition. Because this file is processed by Cycloid to inject StackForms variable values and stored in the config Git repository to keep track of each deployment desired configuration, **please do not add anything else than one or several module calls** in the `main.tf` file. A typical module call looks like this:

* AWS
* Azure
* GCP

terraform/main.tf

```
module "compute" {
  #####################################
  # Do not modify the following lines #
  source   = "./module-compute"
  cy_org       = var.cy_org
  cy_project   = var.cy_project
  cy_env       = var.cy_env
  cy_component = var.cy_component
  #####################################

  #. vm_instance_type: 't3.micro'
  #+ Instance type for the VM
  vm_instance_type = "Value injected by StackForms"

  #. vm_disk_size: 20
  #+ Disk size for the VM (Go)
  vm_disk_size = 20
}
```

terraform/variables.tf

```
module "compute" {
  #####################################
  # Do not modify the following lines #
  source   = "./module-compute"
  cy_org       = var.cy_org
  cy_project   = var.cy_project
  cy_env       = var.cy_env
  cy_component = var.cy_component
  #####################################

  #. vm_instance_type: 'Standard_DS2_v2'
  #+ Instance type for the VM
  vm_instance_type = "Value injected by StackForms"

  #. vm_disk_size: 30
  #+ Disk size for the VM (Go)
  vm_disk_size = 30
}
```

terraform/variables.tf

```
module "compute" {
  #####################################
  # Do not modify the following lines #
  source   = "./module-compute"
  cy_org       = var.cy_org
  cy_project   = var.cy_project
  cy_env       = var.cy_env
  cy_component = var.cy_component
  #####################################

  #. vm_instance_type: 'n2-standard-2'
  #+ Machine type for the VM
  vm_machine_type = "Value injected by StackForms"

  #. vm_disk_size: 20
  #+ Disk size for the VM (Go)
  vm_disk_size = 20
}
```

tip

Please note the invalid value `"Value injected by StackForms"`. This is to illustrate that the Terraform variable values are going to be overridden by StackForms according to the end-user's wishes (cf. Step 8).

The desired configuration is always going to be stored in the config Git repository. When StackForms shows the form, it loads the selected values from the config git, and when the end-user validates a change, StackForms pushes a new commit to your config Git repository to reflect the desired configuration changes. In other words, the source of truth is always your git.

4. Review the `variables.tf` file in the `terraform` folder and adapt as required. This is the declaration of the Terraform variables that will be sent by the pipeline in the next step. They commonly include the Terraform provider credentials.

* AWS
* Azure
* GCP

terraform/variables.tf

```
# Cycloid variables
variable "cy_org" {}
variable "cy_project" {}
variable "cy_env" {}
variable "cy_component" {}

# AWS variables
variable "aws_cred" {
  description = "Contains AWS access_key and secret_key"
}
variable "aws_region" {
  description = "AWS region where to create servers."
  default     = "eu-west-1"
}
```

terraform/variables.tf

```
# Cycloid variables
variable "cy_org" {}
variable "cy_project" {}
variable "cy_env" {}
variable "cy_component" {}

# Cloud variables
variable "azure_cred" {
  description = "The azure credential used to deploy the infrastructure. It contains subscription_id, tenant_id, client_id, and client_secret"
}
```

terraform/variables.tf

```
# Cycloid variables
variable "cy_org" {}
variable "cy_project" {}
variable "cy_env" {}
variable "cy_component" {}

# GCP variables
variable "gcp_project" {}
variable "gcp_region" {
  description = "GCP region where to create servers."
  default     = "europe-west1"
}
variable "gcp_zone" {
  description = "GCP zone where to create servers."
  default     = "europe-west1-b"
}
```

5. Review the `provider.tf` file in the `terraform` folder and adapt as required. It commonly uses the credentials provided by the pipeline.

* AWS
* Azure
* GCP

terraform/provider.tf

```
provider "aws" {
  access_key = var.aws_cred.access_key
  secret_key = var.aws_cred.secret_key
  region     = var.aws_region
}
```

terraform/provider.tf

```
provider "azurerm" {
  features {}
  client_id       = var.azure_cred.client_id
  client_secret   = var.azure_cred.client_secret
  subscription_id = var.azure_cred.subscription_id
  tenant_id       = var.azure_cred.tenant_id
  environment     = "public"
}
```

terraform/provider.tf

```
provider "google" {
  project = var.gcp_project
  region  = var.gcp_region
  zone    = var.gcp_zone
}
```

6. Review the `pipeline.yml` file in the `pipeline` folder and adapt it as required. You should pass the expected Terraform variables as stated in the previous step.

* AWS
* Azure
* GCP

pipeline/pipeline.yml

```
resources:
- name: tfstate
  type: terraform
  icon: terraform
  source:
    env_name: ($ .env $)
    backend_type: http
    backend_config:
      address: '($ .api_url $)/inventory?jwt=($ .inventory_jwt $)'
    vars:
      aws_cred: ((aws_cred))
      aws_region: ((aws_region))
      cy_org: ($ .org $)
      cy_project: ($ .project $)
      cy_env: ($ .env $)
      cy_component: ($ .component $)
```

pipeline/pipeline.yml

```
resources:
- name: tfstate
  type: terraform
  icon: terraform
  source:
    env_name: ($ .env $)
    backend_type: http
    backend_config:
      address: '($ .api_url $)/inventory?jwt=($ .inventory_jwt $)'
    vars:
      azure_cred: ((azure_cred))
      cy_org: ($ .org $)
      cy_project: ($ .project $)
      cy_env: ($ .env $)
      cy_component: ($ .component $)
```

pipeline/pipeline.yml

```
resources:
- name: tfstate
  type: terraform
  icon: terraform
  source:
    env_name: ($ .env $)
    backend_type: http
    backend_config:
      address: '($ .api_url $)/inventory?jwt=($ .inventory_jwt $)'
    vars:
      gcp_project: ((gcp_project))
      gcp_region: ((gcp_region))
      gcp_zone: ((gcp_zone))
      cy_org: ($ .org $)
      cy_project: ($ .project $)
      cy_env: ($ .env $)
      cy_component: ($ .component $)
    env:
      GOOGLE_PROJECT: ((gcp_project))
      GOOGLE_REGION: ((gcp_region))
      GOOGLE_ZONE: ((gcp_zone))
      GOOGLE_CREDENTIALS: ((gcp_credentials_json))
```

7. Review the `variables.sample.yml` file in the `pipeline` folder and make sure at least the above variables in double parenthesis are declared. Typically, it should look like this:

* AWS
* Azure
* GCP

pipeline/variables.sample.yml

```
#. aws_cred (required): ((aws))
#+ Amazon credentials containing access key and secret key for Terraform.
aws_cred: ((aws))

#. aws_region (required): "eu-west-3"
#+ AWS region to use for Terraform.
aws_region: "eu-west-3"
```

pipeline/variables.sample.yml

```
#. azure_cred (required): ((azure))
#+ The azure credential used to deploy the infrastructure. It contains subscription_id, tenant_id, client_id, and client_secret. See value format [here](https://docs.cycloid.io/advanced-guide/integrate-and-use-cycloid-credentials-manager.html#vault-in-the-pipeline)
azure_cred: ((azure))
```

pipeline/variables.sample.yml

```
#. gcp_credentials_json (required): ((gcp.json_key))
#+ Google Cloud Platform JSON credentials to use for Terraform. See value format [here](https://docs.cycloid.io/advanced-guide/integrate-and-use-cycloid-credentials-manager.html#vault-in-the-pipeline)
gcp_credentials_json: ((gcp.json_key))

#. gcp_project (required): ""
#+ Google Cloud Platform project ID for Terraform.
gcp_project: ""

#. gcp_region (required): "europe-west1"
#+ Google Cloud Platform region to use for Terraform.
gcp_region: "europe-west1"

#. gcp_zone (required): "europe-west1-b"
#+ Google Cloud Platform zone to use for Terraform.
gcp_zone: "europe-west1-b"
```

tip

`((my_cred_name))` refers to a credential with canonical name `my_cred_name`. Please visit Security ➔ Credentials in the Cycloid console to manage your credentials. It will be the default value unless the value is overridden by StackForms.

`($ .component $), ($ .env $)` and `($ .project $)` are Cycloid [special variables](/reference/stacks/concepts/templating.md#special-variables) replaced at pipeline instantiation. These variables come from the project and environment canonical names as entered by the end-user in the Cycloid console.

`($ .org $)` would be replaced by the organization's canonical name where the project has been created.

The pipeline variables default values will be taken into account only if they are not overridden by StackForms. As an example, check the GCP implementation where `gcp_region` and `gcp_zone` have no StackForms widgets. That means the pipeline default values above will be the values provided to the Terraform module.

8. Edit the `.forms.yml` file in the root folder, and adapt the pipeline and terraform variables accordingly. For more information on how to use StackForms, please go to the dedicated [StackForms Cookbook section](/cookbook/getting-started/devops-teams/stackforms/.md) or the [StackForms Reference manual](/reference/stackforms/.md).

* AWS
* Azure
* GCP

.forms.yml

```
version: "2"
use_cases:
- name: default
  sections:
  - name: AWS Cloud Provider
    groups:
    - name: Access Configuration
      technologies: [pipeline]
      vars:
      - name: "AWS Account"
        description: "The AWS account where to deploy the infrastructure. It contains an access key and secret key."
        key: aws_cred
        widget: cy_cred
        widget_config:
          display_keys: false
          cred_types:
            - aws
        type: string
        default: "((aws))"
        required: true
      - name: "AWS Region"
        description: "AWS region to use for Terraform."
        key: aws_region
        widget: auto_complete
        type: string
        values_ref: https://cycloid-demo-stackforms-values.s3.eu-west-1.amazonaws.com/aws-regions.json
        default: eu-west-3
        required: true

    - name: Virtual machine specifications
      technologies: [terraform]
      vars:
      - name: "Instance type"
        description: "Instance type for the VM."
        key: vm_instance_type
        widget: slider_list
        type: string
        default: "t3a.small"
        values:
            - "t3a.small"
            - "t3a.medium"
            - "t3a.large"
        required: true
      - name: "Disk size"
        unit: Go
        description: "Disk size for the VM."
        key: vm_disk_size
        widget: slider_range
        type: integer
        default: 20
        values:
            - 20
            - 250
        required: true
```

.forms.yml

```
version: "2"
use_cases:
- name: default
  sections:
  - name: Instance
    groups:
    - name: Azure Access Configuration
      technologies: [pipeline]
      vars:
      - name: "Azure credentials"
        description: "The azure credential used to deploy the infrastructure. It contains subscription_id, tenant_id, client_id, and client_secret."
        key: azure_cred
        widget: cy_cred
        widget_config:
          display_keys: false
          cred_types:
            - azure
        type: string
        default: "((azure))"
        required: true

    - name: Virtual machine specifications
      technologies: [terraform]
      vars:
      - name: "Instance type"
        description: "Instance type for the VM."
        key: vm_instance_type
        widget: slider_list
        type: string
        default: "Standard_DS2_v2"
        values:
            - "Standard_DS1_v2"
            - "Standard_DS2_v2"
            - "Standard_DS3_v2"
        required: true
      - name: "Disk size"
        unit: Go
        description: "Disk size for the VM."
        key: vm_disk_size
        widget: slider_range
        type: integer
        default: 20
        values:
            - 20
            - 250
        required: true
```

.forms.yml

```
version: "2"
use_cases:
- name: default
  sections:
  - name: GCP Cloud Provider
    groups:
    - name: GCP Access Configuration
      technologies: [pipeline]
      vars:
      - name: "GCP credentials"
        description: "Google Cloud Platform JSON credentials to use for Terraform."
        key: gcp_credentials_json
        widget: cy_cred
        widget_config:
          display_keys: true
          cred_types:
            - gcp
        type: string
        default: "((gcp.json_key))"
        required: true
      - name: "GCP project"
        description: "Google Cloud Platform project ID for Terraform."
        key: gcp_project
        widget: simple_text
        type: string
        default: ""
        required: true

    - name: Virtual machine specifications
      technologies: [terraform]
      vars:
      - name: "Machine type"
        description: "Machine type for the VM."
        key: vm_instance_type
        widget: slider_list
        type: string
        default: "n2-standard-2"
        values:
            - n2-standard-2
            - n2d-standard-2
            - n2d-standard-4
        required: true
      - name: "Disk size"
        unit: Go
        description: "Disk size for the VM."
        key: vm_disk_size
        widget: slider_range
        type: integer
        default: 20
        values:
            - 20
            - 250
        required: true
```

tip

Note the `technologies` attribute. When set to `pipeline`, the underneath variables will override pipeline variable values in `pipeline/variables.sample.yml` and when set to `terraform`, the values will be injected in the module variables as called in the `terraform/main.tf.sample` file.

9. Finally, you may want to edit the `.cycloid.yml` file to change the stack metadata displayed to end-users on the Cycloid portal.
10. Commit and push the changes to your Git repository.
11. Refresh the service catalog from the `Refresh` button in the `Catalog repositories` tab from the `Stacks` page

Congratulations ! You can now test your Stack as a end-user would do by [creating a project](/cookbook/getting-started/end-users/deploy.md).


---

# StackForms

After you create a Stack and you make customizations to support your use case, let's review more advanced StackForms use cases.

This allows the end-users to configure their environment with maximum flexibility while ensuring the governance your organization requires.

Let's deep dive into these common StackForms use cases:

* [The end-user selects a cloud account and a region](/cookbook/getting-started/devops-teams/stackforms/account.md)
* [The end-user selects a VPC and a subnet](/cookbook/getting-started/devops-teams/stackforms/network/.md)

Concepts

We use a module called StackForms to gather end-users Environment desired configurations with easy-to-use forms. The DevOps team has full control of the StackForms design.

Please refer to the [Reference guide](/reference/stackforms/introduction.md) for more information about the StackForms concepts.


---

# Selecting Account and Region

This use case allows your end-users to select a cloud account and a region from available options. If your deployment requires several accounts and/or regions, you can duplicate the same setup as required.

tip

If you always want to use the same cloud account(s) and region(s) (your end-users won't have control on it), you will need to set them up, typically as default values in your pipeline variables. In this case, this use case is irrelevant.

1. Ensure your cloud accounts credentials are stored in Cycloid Vault. From the left menu on the Cycloid console, click on **Security** ➔ **Credentials**, then click the **Add Credential** button. Fill in the new credential form with the right type (AWS, Azure, GCP, VMware).
2. From the left menu on the Cycloid console, click on **Stacks** ➔ **Tools**, then on **StackForms Editor**. You can have a look at the proposed samples but for now, we are going to paste this code as a starting point for our use case:

* AWS
* Azure
* GCP

.forms.yml

```
---
version: "2"
use_cases:
- name: default
  sections:
  - name: AWS Cloud Provider
    groups:
    - name: Access Configuration
      technologies: [pipeline]
      vars:
      - name: "AWS Account"
        description: "The AWS account where to deploy the infrastructure, containing access and secret keys."
        key: aws_cred
        widget: cy_cred
        widget_config:
          display_keys: false
          cred_types:
            - aws
        type: string
        default: "((aws))"
        required: true
      - name: "AWS Region"
        description: "AWS region to use for Terraform."
        key: aws_region
        widget: auto_complete
        type: string
        values_ref: https://cycloid-demo-stackforms-values.s3.eu-west-1.amazonaws.com/aws-regions.json
        default: eu-west-3
        required: true
```

.forms.yml

```
---
version: "2"
use_cases:
- name: default
  sections:
  - name: Azure Cloud Provider
    groups:
    - name: Access Configuration
      technologies: [pipeline]
      vars:
      - name: "Azure credentials"
        description: "The azure credential used to deploy the infrastructure. It contains subscription_id, tenant_id, client_id, and client_secret."
        key: azure_cred
        widget: cy_cred
        widget_config:
          display_keys: false
          cred_types:
            - azure
        type: string
        default: "((azure))"
        required: true
      - name: "Azure location"
        description: "Azure location for Terraform."
        key: azure_location
        widget: auto_complete
        type: string
        values_ref: https://cycloid-demo-stackforms-values.s3.eu-west-1.amazonaws.com/azure-locations.json
        default: "West Europe"
        required: true
```

.forms.yml

```
---
version: "2"
use_cases:
- name: default
  sections:
  - name: GCP Cloud Provider
    groups:
    - name: Access Configuration
      technologies: [pipeline]
      vars:
      - name: "GCP credentials"
        description: "Google Cloud Platform JSON credentials to use for Terraform."
        key: gcp_credentials_json
        widget: cy_cred
        widget_config:
          display_keys: true
          cred_types:
            - gcp
        type: string
        default: "((gcp.json_key))"
        required: true
      - name: "GCP project"
        description: "Google Cloud Platform project ID for Terraform."
        key: gcp_project
        widget: simple_text
        type: string
        default: ""
        required: true
      - name: "GCP region"
        description: "Google Cloud Platform region to use for Terraform."
        key: gcp_region
        widget: auto_complete
        type: string
        values_ref: https://cycloid-demo-stackforms-values.s3.eu-west-1.amazonaws.com/gcp-regions.json
        required: true
```

tip

This StackForms code allows the end-user to select one account and one region. This information will be transmitted to the pipeline (and then eventually to your terraform providers).

To select the credentials we created in step 1. we use the [`cy_cred`](/reference/stackforms/reference/widgets/cy_cred.md) StackForms widget with the right [type of credential](/reference/credentials/concepts.md) for your cloud provider. This will list the credentials available in the Cycloid organization to which the end-user belongs to. Note that you can also filter this list based on the assigned end-user RBAC role.

To select the region, we use an [`auto_complete`](/reference/stackforms/reference/widgets/auto_complete.md) StackForms widget where we fetch the proposed options from a static endpoint. This way, you can easily update the suggested regions. If you want to enforce the selection of a region from the proposed options, you can use a [`dropdown`](/reference/stackforms/reference/widgets/dropdown.md) widget instead.

Alternatively, you can list the regions directly in the widget definition if you don't want to use an API call to retrieve the list of regions. To do so, please check the usage of [values and values\_ref](/reference/stackforms/concepts/variables.md#values-and-values_ref) attributes.

3. Adapt the StackForms code, especially the name of the variables and the endpoints where the options are retrieved. Click the **Validate** button and check the rendered StackForms to see if it fits your expectations.
4. Copy the above validated StackForms code and paste it into your `.forms.yml` file in the stack you are creating (cf. [Create a stack from a blueprint](/cookbook/getting-started/devops-teams/stack-creation/blueprint.md)).

info

The `.forms.yml` file is at the root folder of your newly created stack. It is typically located in the stacks branch of the git repository declared as your [service catalog](/reference/config-and-catalog-repository/.md).

5. Because we want to send these variables to the pipeline, ensure they are declared in the `variables.sample.yml` file in the `pipeline` folder. It should look like this:

* AWS
* Azure
* GCP

pipeline/variables.sample.yml

```
#. aws_cred (required): ((aws))
#+ Amazon credentials containing access key and secret key for Terraform.
aws_cred: ((aws))

#. aws_region (required): "eu-west-3"
#+ AWS region to use for Terraform.
aws_region: "eu-west-3"
```

pipeline/variables.sample.yml

```
#. azure_cred (required): ((azure))
#+ The azure credential used to deploy the infrastructure. It contains subscription_id, tenant_id, client_id, and client_secret. See value format [here](https://docs.cycloid.io/advanced-guide/integrate-and-use-cycloid-credentials-manager.html#vault-in-the-pipeline)
azure_cred: ((azure))
```

pipeline/variables.sample.yml

```
#. gcp_credentials_json (required): ((gcp.json_key))
#+ Google Cloud Platform JSON credentials to use for Terraform. See value format [here](https://docs.cycloid.io/advanced-guide/integrate-and-use-cycloid-credentials-manager.html#vault-in-the-pipeline)
gcp_credentials_json: ((gcp.json_key))

#. gcp_project (required): ""
#+ Google Cloud Platform project ID for Terraform.
gcp_project: ""

#. gcp_region (required): "europe-west1"
#+ Google Cloud Platform region to use for Terraform.
gcp_region: "europe-west1"
```

6. Review the `pipeline.yml` file in the `pipeline` folder and ensure to pass the variables to your Terraform module. They are commonly used in the Terraform provider declaration.

* AWS
* Azure
* GCP

pipeline/pipeline.yml

```
resources:
- name: tfstate
  type: terraform
  icon: terraform
  source:
    env_name: ((env))
    backend_type: http
    backend_config:
      address: '((cycloid_api_url))/inventory?jwt=($ inventory_jwt $)'
    vars:
      aws_cred: ((aws_cred))
      aws_region: ((aws_region))
      cy_org: ($ .org $)
      cy_project: ($ .project $)
      cy_env: ($ .env $)
      cy_component: ($ .component $)
```

pipeline/pipeline.yml

```
resources:
- name: tfstate
  type: terraform
  icon: terraform
  source:
    env_name: ((env))
    backend_type: http
    backend_config:
      address: '((cycloid_api_url))/inventory?jwt=($ inventory_jwt $)'
    vars:
      azure_cred: ((azure_cred))
      cy_org: ($ .org $)
      cy_project: ($ .project $)
      cy_env: ($ .env $)
      cy_component: ($ .component $)
```

pipeline/pipeline.yml

```
resources:
- name: tfstate
  type: terraform
  icon: terraform
  source:
    env_name: ((env))
    backend_type: http
    backend_config:
      address: '((cycloid_api_url))/inventory?jwt=($ inventory_jwt $)'
    vars:
      gcp_project: ((gcp_project))
      gcp_region: ((gcp_region))
      cy_org: ($ .org $)
      cy_project: ($ .project $)
      cy_env: ($ .env $)
      cy_component: ($ .component $)
    env:
      GOOGLE_PROJECT: ((gcp_project))
      GOOGLE_REGION: ((gcp_region))
      GOOGLE_ZONE: ((gcp_zone))
      GOOGLE_CREDENTIALS: ((gcp_credentials_json))
```

7. Review the `variables.tf` file in the `terraform` folder and adapt as required. This is the declaration of the Terraform variables sent by the pipeline in the next step. They commonly include the Terraform provider credentials.

* AWS
* Azure
* GCP

terraform/variables.tf

```
# Cycloid variables
variable "cy_org" {}
variable "cy_project" {}
variable "cy_env" {}
variable "cy_component" {}

# AWS variables
variable "aws_cred" {
  description = "Contains AWS access_key and secret_key"
}
variable "aws_region" {
  description = "AWS region where to create servers."
  default     = "eu-west-3"
}
```

terraform/variables.tf

```
# Cycloid variables
variable "cy_org" {}
variable "cy_project" {}
variable "cy_env" {}
variable "cy_component" {}

# Cloud variables
variable "azure_cred" {
  description = "The azure credential used to deploy the infrastructure. It contains subscription_id, tenant_id, client_id, and client_secret"
}
```

terraform/variables.tf

```
variable "cy_org" {}
variable "cy_project" {}
variable "cy_env" {}
variable "cy_component" {}

# GCP variables
variable "gcp_project" {}
variable "gcp_region" {
  description = "GCP region where to create the infrastructure."
  default     = "europe-west1"
}
variable "gcp_zone" {
  description = "GCP zone where to create the infrastructure."
  default     = "europe-west1-b"
}
```

8. Review the `provider.tf` file in the `terraform` folder and adapt as required. It commonly uses the credentials provided by the pipeline.

* AWS
* Azure
* GCP

terraform/provider.tf

```
provider "aws" {
  access_key = var.aws_cred.access_key
  secret_key = var.aws_cred.secret_key
  region     = var.aws_region
}
```

terraform/provider.tf

```
provider "azurerm" {
  features {}
  client_id       = var.azure_cred.client_id
  client_secret   = var.azure_cred.client_secret
  subscription_id = var.azure_cred.subscription_id
  tenant_id       = var.azure_cred.tenant_id
  environment     = "public"
}
```

terraform/provider.tf

```
provider "google" {
  project = var.gcp_project
  region  = var.gcp_region
}
```

9. Commit and push your changes to your stacks git repository.
10. Refresh the service catalog from the `Refresh` button in the `Catalog repositories` tab on the `Stacks` page.
11. Finally, [create a project](/cookbook/getting-started/end-users/deploy.md) using your new stack.


---

# Selecting VPC and subnets

This use case allows your end-users to select an existing VPC and subnet, for example, to deploy new resources. The goal is to conveniently propose VPC and subnet options to the end-users.

Of course, the mechanisms shown in this section can be applied to many others use cases.

There are different ways to get the VPC and subnet options:

* [From the Cycloid Asset Inventory](/cookbook/getting-started/devops-teams/stackforms/network/asset_inventory.md) if the networking resources have been previously deployed with Cycloid platform and therefore they are visible in the Cycloid Asset Inventory.
* [Using static data from an API endpoint](/cookbook/getting-started/devops-teams/stackforms/network/api_static_values.md) to get the options using an external API. This would be typically a cloud storage bucket where static website hosting is enabled.
* [Using dynamic data from an API endpoint](/cookbook/getting-started/devops-teams/stackforms/network/api_dynamic_values.md) for maximum flexibility and customization. This use case is technically advanced and requires programming language skills, for example to build functions.


---

# Dynamic data from an API endpoint

This use case allows the end-user to select a VPC and one or several subnets among network resources retrieved from an external third-party API.

We are going to use the [values\_ref](/reference/stackforms/concepts/dynamic-values.md) attribute of the [dropdown](/reference/stackforms/reference/widgets/dropdown.md) widget to do the API integration.

In this use case, the Cycloid widget will call an AWS lamdba function API endpoint as defined in the `values_ref` attribute. It expects to receive a JSON array which will be the list of options presented to the end-user. The returned payload should look like this:

```
[
    "vpc-01294bea93d6af1d6",
    "vpc-70ae3d17"
]
```

info

This is a simple example of such an API implementation (not suitable for production purposes).

Please adapt it for Azure Functions, Google Cloud Functions, Node JS on an instance, etc. to implement your API according to your requirements as long as it returns the expected format.

tip

If you need to label the options differently to be more user friendly, you may want want to have a look at [Map value mapping](/reference/stackforms/concepts/value-mapping.md).

1. Go to your AWS console and create a Lambda function. Name it `ListVpcs` and select the latest supported version of Python as Runtime.
2. Expand `Advanced Settings` and check `Enable function URL` with `NONE` as authentication. Create the function.
3. Paste the following Python code and clic on the `Deploy` button:

```
import json
import boto3

def lambda_handler(event, context):
    region = event.get('queryStringParameters',{}).get('region','none')
    if region == 'none':
        client = boto3.client('ec2')
    else:
        client = boto3.client('ec2', region)

    client_response = client.describe_vpcs()

    response = []
    for item in client_response['Vpcs']: 
        response.append(item["VpcId"])

    return {
        'statusCode': 200,
        'body': json.dumps(response)
    }
```

info

The goal is to be able to call this function with a URL. Optionally, a `region` query parameter can be added to scope the VPC list to a given region.

The called URL should look like this: `https://ghkcehkmli.lambda-url.us-east-1.on.aws/`. Put aside this URL as we'll need it later on.

tip

If you get an `Internal Server Error` due to the lambda function exceeding the default 3 seconds timeout, you may want to increase your lambda function timeout.

4. In your AWS console, go to the the IAM role created for your `ListVpcs` Lambda (it should be named `ListVpcs-role-<xyz>`) and add the inline permission `ec2:DescribeVpcs`. This will allow the lambda function to retrieve a list of VPCs deployed in your account.
5. Create a second Lambda function with the name `ListSubnets` (again, make sure to check `Enable function URL`).
6. Paste the following Python code and clic on the `Deploy` button:

```
import json
import boto3

def lambda_handler(event, context):
    vpcId = event.get('queryStringParameters',{}).get('vpc-id','none')
    if vpcId == 'none':
        filters = []
    else:
        filters = [ { 'Name': 'vpc-id', 'Values': [ vpcId, ] } ]

    client = boto3.client('ec2')
    client_response = client.describe_subnets(Filters=filters)

    response = []
    for item in client_response['Subnets']: 
        response.append(item["SubnetId"])

    return {
        'statusCode': 200,
        'body': json.dumps(response)
    }
```

tip

The goal is to be able to call this function with a URL. A `vpc-id` query parameter can be added to scope the subnet list to a given VPC.

The called URL should look like this: `https://cxgsfegamp.lambda-url.us-east-1.on.aws/?vpc-id=vpc-xpfdtahgh`. Put aside this URL as we'll need it later on.

7. In your AWS console, go to the the IAM role created for your `ListSubnets` Lambda (it should be named `ListSubnets-role-<xyz>`) and add the inline permission `ec2:DescribeSubnets`. This will allow the lambda function to retrieve a list of subnets deployed in your account.
8. Now, let's build 2 StackForms dropdown widgets allowing the end-user to select a VPC and then a subnet belonging to the selected VPC. From the left menu on the Cycloid console, click on **Stacks** ➔ **Tools**, then **StackForms Editor**. You can have a look at the proposed samples but for now, we are going to paste this code for our use case:

```
---
version: "2"
use_cases:
- name: default
  sections:
  - name: AWS Cloud Provider
    groups:
    - name: Networking
      technologies: [terraform]
      vars:
      - name: "VPC"
        description: "VPC where to deploy the resources."
        key: vpc_id
        widget: dropdown
        values_ref: 'https://34demb6crtlu2vbflbivpxxyx40yjpzj.lambda-url.eu-west-3.on.aws/?region=eu-west-3'
        type: string
        required: true
      - name: "Subnet"
        description: "Subnets where to deploy the resources."
        key: subnet_id
        widget: dropdown
        values_ref: 'https://bw6xnnq22lanndxjllrds5luqa0rhnaa.lambda-url.eu-west-3.on.aws/?vpc-id=${vpc_id}'
        type: string
        required: true
```

tip

If you need the end-user to select multiple subnets, and eventually enforce a minimum and a maximum number of seleted items, please have a look at the [multiselect dropdown](/reference/stackforms/reference/widgets/dropdown.md#attribute-multiselect) widget and [Array validation](/reference/stackforms/concepts/value-validations.md#array-validation-example).

A code snippet of a multiselect dropdown widget to select between 2 and 3 subnets would look like this:

```
      - name: "Subnet"
        description: "Subnets where to deploy the resources."
        key: subnet_ids
        widget: dropdown
        widget_config:
          multiselect: true
        values_ref: 'https://bw6xnnq22lanndxjllrds5luqa0rhnaa.lambda-url.eu-west-3.on.aws/?vpc-id=${vpc_id}'
        type: array
        required: true
        validations:
          - array:
              min_elems: 2
            error_message: "At least two subnets must be selected"
          - array:
              max_elems: 3
            error_message: "No more than three subnets must be selected"
```

9. Adapt the StackForms code, especially the lambda URL. Click the **Validate** button and check if the rendered StackForms fits your expectations.
10. Copy the final validated StackForms code and paste it to your `.forms.yml` in the target stacks.
11. As we send these variables to your Terraform module directly (thanks to `technologies: [terraform]`), there is no need to add these variables to the pipeline. Instead, we only need to make sure they are variables we're going to provide to the Terraform module called from `terraform/main.tf.sample`.

terraform/main.tf.sample

```
module "compute" {
  #####################################
  # Do not modify the following lines #
  source   = "./module-compute"
  cy_org       = var.cy_org
  cy_project   = var.cy_project
  cy_env       = var.cy_env
  cy_component = var.cy_component
  #####################################

[...]

  #. vpc_id: ''
  #+ VPC ID where to deploy the resources
  vpc_id = "Value injected by StackForms"

  #. subnet_id: ''
  #+ Subnet ID where to deploy the resources
  subnet_id = "Value injected by StackForms"
}
```

info

Please note the invalid value `"Value injected by StackForms"`. This is to illustrate that the Terraform variable value is going to be overridden by StackForms.

The desired configuration will always be stored in the config Git repository. When StackForms shows the form, it loads the selected values from the config git, and when the end-user validates a change, StackForms pushes a new commit to your config Git repository to reflect the desired configuration changes that the pipeline will apply. In other words, the source of truth is always your git.

12. Make sure the called Terraform module declares the variables we are sending.
13. Adapt the Terraform module according to your needs.
14. Commit and push your changes to your stacks git repository.
15. Refresh the service catalog from the `Refresh` button in the `Catalog repositories` tab on the `Stacks` page.
16. Finally, [create a Component](/cookbook/getting-started/end-users/deploy.md) using your new stack.


---

# Static data from an API endpoint

This use case allows the end-user to select a VPC and one or several subnets among network resources retrieved from an external third-party API where static data is stored, typically from a cloud storage bucket.

We are going to use the [values\_ref](/reference/stackforms/concepts/dynamic-values.md) attribute of the [dropdown](/reference/stackforms/reference/widgets/dropdown.md) widget to do the API integration.

info

The Cycloid widget will call the API endpoint defined in the `values_ref` attribute and expects to get a JSON array which will be the list of options presented to the end-user.

The expected format is a flat JSON array. It is the same format for the `values` attribute when it is harcoded in the `.forms.yml` file and when it is retrieved from an API endpoint. More information about the expected format can be found [in the reference guide](/reference/stackforms/concepts/dynamic-values.md)

1. In the stack you are creating (cf. [Create a stack from a blueprint](/cookbook/getting-started/devops-teams/stack-creation/blueprint.md)), let's build the StackForms widget that allows the end-user to select a VPC and subnet. From the left menu on the Cycloid console, click on **Stacks** ➔ **Tools**, then **StackForms Editor**. You can look at the proposed samples but for now, we are going to paste this code as a starting point for our use case:

* AWS
* Azure
* GCP

.forms.yml

```
---
version: "2"
use_cases:
- name: default
  sections:
  - name: AWS Cloud Provider
    groups:
    - name: Networking
      technologies: [terraform]
      vars:
      - name: "VPC"
        description: "VPC where to deploy the resources."
        key: vpc_id
        widget: dropdown
        values_ref: 'https://cycloid-demo-stackforms-values.s3.eu-west-1.amazonaws.com/aws-vpc-ids-eu-west-3.json.json'
        type: string
        required: true
      - name: "Subnet"
        description: "Subnets where to deploy the resources."
        key: subnet_id
        widget: dropdown
        values_ref: 'https://cycloid-demo-stackforms-values.s3.eu-west-1.amazonaws.com/aws-subnet-ids-${vpc_id}.json'
        type: string
        required: true
```

```
---
version: "2"
use_cases:
- name: default
  sections:
  - name: Azure Cloud Provider
    groups:
    - name: Networking
      technologies: [terraform]
      vars:
      - name: "Virtual Network"
        description: "Virtual Network where to deploy the resources."
        key: vnet_name
        widget: dropdown
        values_ref: 'https://cycloid-demo-stackforms-values.s3.eu-west-1.amazonaws.com/azure-vnet-names.json'
        type: string
        required: true
      - name: "Subnet"
        description: "Subnet where to deploy the resources."
        key: subnet_id
        widget: dropdown
        values_ref: 'https://cycloid-demo-stackforms-values.s3.eu-west-1.amazonaws.com/azure-subnet-ids-${vnet_name}.json'
        type: string
        required: true
```

```
---
version: "2"
use_cases:
- name: default
  sections:
  - name: GCP Cloud Provider
    groups:
    - name: Networking
      technologies: [terraform]
      vars:
      - name: "VPC"
        description: "VPC where to deploy the resources."
        key: vpc_id
        widget: dropdown
        values_ref: 'https://cycloid-demo-stackforms-values.s3.eu-west-1.amazonaws.com/gcp-vpc-ids.json'
        type: string
        required: true
      - name: "Subnet"
        description: "Subnet where to deploy the resources."
        key: subnet_id
        widget: dropdown
        values_ref: 'https://cycloid-demo-stackforms-values.s3.eu-west-1.amazonaws.com/gcp-subnet-ids-${vpc_id}.json'
        type: string
        required: true
```

info

This adds dropdown widgets to select the VPC and subnet which are going to be provided to your Terraform module (cf. `technologies` attribute).

We use the [`dropdown`](/reference/stackforms/reference/widgets/dropdown.md) StackForms widget to list the available VPCs and subnets from the API endpoint declared in the `values_ref` attribute. Note the subnet options are filtered according to the selected VPC.

tip

If several subnets are required for redundancy and/or scalability purposes, you can use the [multiselect dropdown widget](/reference/stackforms/reference/widgets/dropdown.md#attribute-multiselect) instead.

Recommendation

Refresh the JSON objects periodically with some scripts to ensure the end-user always gets up to date options. You can usually do that quickly using your cloud provider CLI.

This is an example to retrieve a list of VPCs in a specific region and store the result in a S3 object::

```
aws ec2 describe-vpcs --region eu-west-3 --query "Vpcs[].VpcId" | aws s3 cp - s3://cycloid-demo-stackforms-values/aws-vpc-ids-eu-west-3.json
```

The payload should look like this:

```
[
    "vpc-01294bea93d6af1d6",
    "vpc-70ae3d17"
]
```

Another useful example to list the supported AWS instance types in a specific region and store the result in a S3 object:

```
aws ec2 describe-instance-type-offerings --region eu-west-3 --query "InstanceTypeOfferings[].InstanceType" | jq '. | sort' | aws s3 cp - s3://cycloid-demo-stackforms-values/aws-ec2-instance-types.json
```

2. Adapt the StackForms code, especially the name of the variables according to your needs. Click the **Validate** button and check if the rendered StackForms fits your expectations.
3. Copy the final validated StackForms code and paste it to your `.forms.yml` in the target stacks.
4. As we send these variables to your Terraform module directly (thanks to `technologies: [terraform]`), there is no need to add these variables to the pipeline. Instead, we only need to make sure they are variables we're going to provide to the Terraform module called from `terraform/main.tf`.

* AWS
* Azure
* GCP

terraform/main.tf

```
module "compute" {
  #####################################
  # Do not modify the following lines #
  source   = "./module-compute"
  cy_org       = var.cy_org
  cy_project   = var.cy_project
  cy_env       = var.cy_env
  cy_component = var.cy_component
  #####################################

[...]

  #. vpc_id: ''
  #+ VPC ID where to deploy the resources
  vpc_id = "Value injected by StackForms"

  #. subnet_id: ''
  #+ Subnet ID where to deploy the resources
  subnet_id = "Value injected by StackForms"
}
```

terraform/main.tf

```
module "compute" {
  #####################################
  # Do not modify the following lines #
  source   = "./module-compute"
  cy_org       = var.cy_org
  cy_project   = var.cy_project
  cy_env       = var.cy_env
  cy_component = var.cy_component
  #####################################

[...]

  #. vnet_name: ''
  #+ vNet name where to deploy the resources
  vnet_name = "Value injected by StackForms"

  #. subnet_id: ''
  #+ Subnet ID where to deploy the resources
  subnet_id = "Value injected by StackForms"
}
```

terraform/main.tf

```
module "compute" {
  #####################################
  # Do not modify the following lines #
  source   = "./module-compute"
  cy_org       = var.cy_org
  cy_project   = var.cy_project
  cy_env       = var.cy_env
  cy_component = var.cy_component
  #####################################

[...]

  #. vpc_id: ''
  #+ VPC ID where to deploy the resources
  vpc_id = "Value injected by StackForms"

  #. subnet_id: ''
  #+ Subnet ID where to deploy the resources
  subnet_id = "Value injected by StackForms"
}
```

info

Please note the invalid value `"Value injected by StackForms"`. This is to illustrate that the Terraform variable value is going to be overridden by StackForms.

The desired configuration will always be stored in the config Git repository. When StackForms shows the form, it loads the selected values from the config git, and when the end-user validates a change, StackForms pushes a new commit to your config Git repository to reflect the desired configuration changes that the pipeline will apply. In other words, the source of truth is always your git.

6. Make sure the called Terraform module declares the variables we are sending.
7. Adapt the Terraform module according to your needs.
8. Commit and push your changes to your stacks git repository.
9. Refresh the service catalog from the `Refresh` button in the `Catalog repositories` tab on the `Stacks` page.
10. Finally, [create a Component](/cookbook/getting-started/end-users/deploy.md) using your new stack.


---

# From Cycloid Asset Inventory

This use case allows the end-user to select a VPC and one or several subnets among network resources from the Cycloid Asset Inventory. It contains all resources deployed by Cycloid using Terraform within the same organization. This use case requires that a Cycloid stack using Terraform has been used to deploy the networking resources beforehand.

1. Deploy some networking resources (VPC/vNet and subnets) with a Cycloid stack using Terraform. Ensure the networking resources are present in the [Asset Inventory](/reference/inventory/.md).

tip

If you don't have such a stack, you can use our simple networking [Onboarding Stacks](https://github.com/cycloid-community-catalog/onboarding-stacks/tree/master). We recommend the simple `Landing Zone` stack for your cloud provider.

If you want to use these stacks, please add this URL to your [service catalog](/reference/config-and-catalog-repository/.md): <https://github.com/cycloid-community-catalog/onboarding-stacks.git>.

2. In the stack you are creating (cf. [Create a stack from a blueprint](/cookbook/getting-started/devops-teams/stack-creation/blueprint.md)), let's build the StackForms widget that allows the end-user to select a deployed VPC and subnet. From the left menu on the Cycloid console, click on **Stacks** ➔ **Tools**, then **StackForms Editor**. You can look at the proposed samples but for now, we are going to paste this code as a starting point for our use case:

* AWS
* Azure
* GCP

.forms.yml

```
---
version: "2"
use_cases:
- name: default
  sections:
  - name: AWS Cloud Provider
    groups:
    - name: Networking
      technologies: [terraform]
      vars:
      - name: "VPC"
        description: "VPC where to deploy the resources."
        key: vpc_id
        widget: cy_inventory_resource
        widget_config:
          attribute: id
          filters:
            type: aws_vpc
        type: string
        required: true
      - name: "Subnet"
        description: "Subnets where to deploy the resources."
        key: subnet_id
        widget: cy_inventory_resource
        widget_config:
          attribute: id
          filters:
            type: aws_subnet
            attributes: 'vpc_id[eq]=${vpc_id}'
        type: string
        required: true
```

```
---
version: "2"
use_cases:
- name: default
  sections:
  - name: Azure Cloud Provider
    groups:
    - name: Networking
      technologies: [terraform]
      vars:
      - name: "Virtual Network"
        description: "Virtual Network where to deploy the resources."
        key: vnet_name
        widget: cy_inventory_resource
        widget_config:
          attribute: name
          filters:
            type: azurerm_virtual_network
        type: string
        required: true
      - name: "Subnet"
        description: "Subnet where to deploy the resources."
        key: subnet_id
        widget: cy_inventory_resource
        widget_config:
          attribute: id
          filters:
            type: azurerm_subnet
            attributes: 'virtual_network_name[eq]=${vnet_name}'
        type: string
        required: true
```

```
---
version: "2"
use_cases:
- name: default
  sections:
  - name: Azure Cloud Provider
    groups:
    - name: Networking
      technologies: [terraform]
      vars:
      - name: "VPC"
        description: "VPC where to deploy the resources."
        key: vpc_id
        widget: cy_inventory_resource
        widget_config:
          attribute: self_link
          filters:
            type: google_compute_network
        type: string
        required: true
      - name: "Subnet"
        description: "Subnet where to deploy the resources."
        key: subnet_id
        widget: cy_inventory_resource
        widget_config:
          attribute: id
          filters:
            type: google_compute_subnetwork
            attributes: 'network[eq]=${vpc_id}'
        type: string
        required: true
```

info

This adds form widgets to select the VPC and subnet which are going to be provided to your Terraform module (cf. `technologies` attribute).

We use the [`cy_inventory_resource`](/reference/stackforms/reference/widgets/cy_inventory_resource.md) StackForms widget with the right type of resource for your cloud provider to list the available VPCs and subnets in the asset inventory of the end-user organization.

Note the subnet options are filtered according to the selected VPC with `widget_config.filters.attributes`.

tip

If several subnets are required for redundancy and/or scalability purposes, you can change the widget configuration to the [array type](/reference/stackforms/reference/widgets/cy_inventory_resource.md#attributes-constraints) to allow the end-user to select multiple subnets.

3. Adapt the StackForms code, especially the name of the variables according to your needs. Click the **Validate** button and check if the rendered StackForms fits your expectations.
4. Copy the final validated StackForms code and paste it to your `.forms.yml` in the target stacks.
5. As we send these variables to your Terraform module directly (thanks to `technologies: [terraform]`), there is no need to add these variables to the pipeline. Instead, we only need to make sure they are variables we're going to provide to the Terraform module called from `terraform/main.tf.sample`.

* AWS
* Azure
* GCP

terraform/main.tf.sample

```
module "compute" {
  #####################################
  # Do not modify the following lines #
  source   = "./module-compute"
  cy_org       = var.cy_org
  cy_project   = var.cy_project
  cy_env       = var.cy_env
  cy_component = var.cy_component
  #####################################

[...]

  #. vpc_id: ''
  #+ VPC ID where to deploy the resources
  vpc_id = "Value injected by StackForms"

  #. subnet_id: ''
  #+ Subnet ID where to deploy the resources
  subnet_id = "Value injected by StackForms"
}
```

terraform/main.tf.sample

```
module "compute" {
  #####################################
  # Do not modify the following lines #
  source   = "./module-compute"
  cy_org       = var.cy_org
  cy_project   = var.cy_project
  cy_env       = var.cy_env
  cy_component = var.cy_component
  #####################################

[...]

  #. vnet_name: ''
  #+ vNet name where to deploy the resources
  vnet_name = "Value injected by StackForms"

  #. subnet_id: ''
  #+ Subnet ID where to deploy the resources
  subnet_id = "Value injected by StackForms"
}
```

terraform/main.tf.sample

```
module "compute" {
  #####################################
  # Do not modify the following lines #
  source   = "./module-compute"
  cy_org       = var.cy_org
  cy_project   = var.cy_project
  cy_env       = var.cy_env
  cy_component = var.cy_component
  #####################################

[...]

  #. vpc_id: ''
  #+ VPC ID where to deploy the resources
  vpc_id = "Value injected by StackForms"

  #. subnet_id: ''
  #+ Subnet ID where to deploy the resources
  subnet_id = "Value injected by StackForms"
}
```

info

Please note the invalid value `"Value injected by StackForms"`. This is to illustrate that the Terraform variable value is going to be overridden by StackForms.

The desired configuration will always be stored in the config Git repository. When StackForms shows the form, it loads the selected values from the config git, and when the end-user validates a change, StackForms pushes a new commit to your config Git repository to reflect the desired configuration changes that the pipeline will apply. In other words, the source of truth is always your git.

6. Make sure the called Terraform module declares the variables we are sending.
7. Adapt the Terraform module according to your needs.
8. Commit and push your changes to your stacks git repository.
9. Refresh the service catalog from the `Refresh` button in the `Catalog repositories` tab on the `Stacks` page.
10. Finally, [create a project](/cookbook/getting-started/end-users/deploy.md) using your new stack.


---

# Cycloid for End Users

## Audience[​](#audience "Direct link to Audience")

End users utilize Cycloid self-service portal to manage workloads in their public and private clouds (such as infrastructure lifecycle management and software delivery).

## Objectives[​](#objectives "Direct link to Objectives")

At the end of this section, you will master the creation of Cycloid Projects to deploy and manage infrastructure and applications.

## Prerequisites[​](#prerequisites "Direct link to Prerequisites")

A personal Cycloid account and credentials to access a cloud provider account are required to complete this section.

info

if you do not meet these requirements, you may want to ask your Cycloid platform team to support you.


---

# Create a project

## Overview of Cycloid Basic Concepts[​](#overview-of-cycloid-basic-concepts "Direct link to Overview of Cycloid Basic Concepts")

Cycloid uses the concept of [Projects](/reference/projects/.md), [Environments](/reference/projects/concepts/environments.md), and [Components](/reference/projects/concepts/components.md) to organize end-users workloads. This allows to deploy and integrate different components together to build customized environments using different stacks from a standard catalog that your DevOps team created to address your organization's needs.

![](/img/cookbook/concepts.png)

Recommendation

A component always uses one an only one stack with its StackForms configuration and pipeline, but an environment can contain multiple components using different stacks. In other words, end-users can easily design their solution using different stacks in each environment.

Please refer to the [Reference guide](/reference/stacks/concepts/stack-concept.md) for more information about these concepts.

Let's now describe a bit each of these Cycloid concepts.

### Project[​](#project "Direct link to Project")

[Projects](/reference/projects/.md) keep track of business applications.

It helps to get organized across your deployments, including ownership, maintainers, observability and monitoring of events in your automation.

### Environment[​](#environment "Direct link to Environment")

[Environments](/reference/projects/concepts/environments.md) are used to deploy similar components and configuration for different purposes such as development testing, staging and production use, supporting governance across environments.

End-users can compose solutions using multiple stacks in different components within each environment.

### Component[​](#component "Direct link to Component")

[Components](/reference/projects/concepts/components.md) manage resource deployment, using StackForms to configure and integrate with other components. Each component runs a pipeline using GitOps principles.

Asset inventory & InfraView shows deployed cloud resources at a glance, and the Terraform backend management organizes your infrastructure as code state files.

## Deploy infrastructure and applications[​](#deploy-infrastructure-and-applications "Direct link to Deploy infrastructure and applications")

Prerequisites

To deploy infrastructure in a public or private cloud, you will need credentials from your cloud provider(s) with the required permissions to run the selected Stack. This will allow the automation to create, update, and destroy the infrastructure as needed.

If you have the permissions to create a Cycloid Credential, please refer to the [Reference guide](/reference/credentials/quickstart.md), otherwise you can ask your Platform Team to do it.

First, let's create a Project:

1. From the left menu on the Cycloid console, click on **Projects** menu item.
2. Click the **Create Project** button and give a name to your Project.

Next, we will need to create a first Environment for your Project:

1. Click the **Add environment** button.
2. Give a name to your environment.

Finally, we are going to create our first component

1. Click the **Add component** button.
2. Select the [Stack](/reference/stacks/.md) you want to use in your component.

Recommendation

We suggest starting with the creation of basic compute resources such as one of the `Compute Instance` Stack.

If these Stacks do not show up in your service catalog, please add the following repository from the `Stacks` and then `Catalog Repositories` tab:

* <https://github.com/cycloid-community-catalog/onboarding-stacks.git>

If you don't have the required permissions do add this catalog repository, please contact your Platform Team.

3. Give a name to your component.
4. Fill in the form to configure your component.
5. Click on Estimate costs button (applicable only if the stack uses Terraform and deploys on a public cloud). This is an example of what it looks like:

![](/img/cookbook/stackforms.png)

7. Finally, click on the **Add Component** button. This will trigger the deployment.

Destroy your infrastructure

If you deployed some infrastructure using Terraform, you may want to destroy it and stop paying for it.

To do so, from the project pipeline tab, click on the `destroy` view, click on the `destroy` job (biggest rectangle), and finally click on the `+` at the top right corner to trigger a new build of this job.


---

# Create my Account

First thing first, you must have been invited by email to create your Cycloid account. If you haven't received such an email yet, please contact your Platform Team to be invited to join your Cycloid organization.

Open the registration email, and click **Create My Account** button.

A registration screen shows up. Please fill it in as shown and click **Create Account**.

![](/img/cookbook/register.png)

<br />

That's it! You are now a member of your [organization](/reference/organizations/.md).


---

# Cycloid for Platform teams

## Audience[​](#audience "Direct link to Audience")

This section is intended for Platform teams who operate the Cycloid platform and ensure the governance needed by their organization.

## Objectives[​](#objectives "Direct link to Objectives")

At the end of this section, you will be able to operate your Self-Hosted Cycloid platform and set up organizations for your users with governance and observability. You will learn more about RBAC and Vault modules, managing organizations and using Cycloid Terraform provider to automate these tasks.

## Prerequisites[​](#prerequisites "Direct link to Prerequisites")

* A personal Cycloid account with appropriate permissions is required. Typically the user may join the organization with the Administrator role.


---

# Install a Self-Hosted platform

## Objectives[​](#objectives "Direct link to Objectives")

This section is intended for Platform teams who operate a self-hosted Cycloid platform and need to install and operate a Cycloid platform on their infrastructure.

At the end of this section, you will be able to run the Cycloid platform on your own infrastructure.

* If you are going for a **POC or an evaluation** platform follow the [POC dedicated Platform guide](/cookbook/dedicated-platform/demo-poc/.md).
* If you are going to setup a **production** platform follow the [Production dedicated Platform guide](/cookbook/dedicated-platform/.md).

## Prerequisites[​](#prerequisites "Direct link to Prerequisites")

* Cycloid provided the credentials to access our Container Registry.
* Cycloid provided the license key to activate the platform once it is installed.


---

# Set Up an Organization

The following section will cover the first steps to finalize the setup of your own Cycloid platform. You will set up base features in a Cycloid organization for all users of the platform.


---

# Connect your Cloud

## Add your credentials to the Vault[​](#add-your-credentials-to-the-vault "Direct link to Add your credentials to the Vault")

info

Your automation needs access to a cloud account to deploy and manage your IaaS and PaaS, for example when using Terraform. Cycloid securely stores secrets and manages access by leveraging state-of-the-art components such as Hashicorp Vault OSS and Role-Based Access Control modules.

This onboarding guide covers AWS, Azure and GCP, but of course you can connect any other cloud such as VMware, Alibaba Cloud, IBM Cloud, Oracle Cloud Infrastructure (OCI), etc. or a Kubernetes cluster directly if you only need to deploy K8s workloads. If you need more information, please contact <support@cycloid.io>

Please follow the instructions for your preferred cloud provider: [AWS](#using-aws), [Azure](#using-azure) or [GCP](#using-gcp).

## Using AWS[​](#using-aws "Direct link to Using AWS")

In your AWS console, go to `IAM`, create a new user, and grant access to the following permission policies (if you don't have already one):

1. Create EC2 compute instances and associated security groups. Ideally, grant permission policy `AmazonEC2FullAccess`.
2. Create basic networking resources such as VPC, subnet and internet gateway. Ideally, grant permission policy `AmazonVPCFullAccess`.
3. Read and write permissions on the S3 bucket used as Terraform backend for tfstate files. Ideally, grant permission policy `AmazonS3FullAccess`.
4. Make sure to have permission to issue `STS:GetCallerIdentity`.

In the new user page, go to the `Security credentials` tab and create `Access keys`. **Put aside the secret for the next step**.

Let’s save your AWS credential in Cycloid Vault:

1. From the left menu on the Cycloid console, click on **Security** ➔ **Credentials**, and then click the **Add Credential** button.
2. Fill in the new credential form with **aws** as the name, **AWS** as the type and then paste your access key and secret key like this:

![](/img/cookbook/aws_cred.png)

tip

For the onboarding free trial, we are going to securely pass this user access key and secret key to the AWS terraform provider to create the infrastructure.

For your future use cases, you could also create a role with the same permission policies and attach it to the EC2 instance running the Cycloid worker.

## Using Azure[​](#using-azure "Direct link to Using Azure")

You will need a service principal with `Contributor` role for your Azure subscription.

To create it, please run:

```
az ad sp create-for-rbac --name <service_principal_name> --role Contributor --scopes /subscriptions/<subscription_id>
```

where:

* `<service_principal_name>` is the service principal name to be created.
* `<subscription_id>` is the Azure subscription associated with the service principal.

tip

To run this command successfully, your Azure user will need either the `Owner` or the `User Access Administrator` role assignment.

For more information on the creation of a service principal for Terraform, please visit [Azure documentation](https://learn.microsoft.com/en-us/azure/developer/terraform/authenticate-to-azure?tabs=bash#create-a-service-principal).

Now, let’s save your new Azure credentials in Cycloid Vault:

1. From the left menu on the Cycloid console, click on **Security** ➔ **Credentials**, and then click the **Add Credential** button.
2. Fill in the new credential form with **azure** as the name, **Azure** as the type and then paste your credentials like this:

![](/img/cookbook/azure_cred.png)

tip

The service principal creation command returns attributes that maps directly into the Cycloid credential as follows:

* `appId` maps to `client_id`
* `password` maps to `client_secret`
* `tenant` maps to `tenant_id`

You will finally need to fill in your `subscription_id` in the credentials form.

## Using GCP[​](#using-gcp "Direct link to Using GCP")

The GCP account credential will require the following permissions:

1. Create virtual machines and associated firewall rules
2. Create basic networking resources such as VPC and subnet
3. Read and write permissions on the Cloud Storage bucket used as Terraform backend for tfstate files

Let’s save your GCP credential in Cycloid Vault:

1. From the left menu on the Cycloid console, click on **Security** ➔ **Credentials**, and then click the **Add Credential** button.
2. Fill in the new credential form with **gcp** as the name, **GCP** as the type and then paste your json key like this:

![](/img/cookbook/gcp_cred.png)


---

# GitOps set up

## Create your Git repository[​](#create-your-git-repository "Direct link to Create your Git repository")

1. Create a new **empty and private** Git repository and name it `cycloid-onboarding`.

tip

Cycloid supports a wide choice of git systems, such as Github, Gitlab, Azure DevOps, BitBucket, AWS CodeCommit, GCP Cloud Source Repositories.

2. Create and copy your credential allowing you to remotely connect to this newly created Git repository. **Put aside the credential for the next steps**.

tip

Both **access tokens** and **SSH keys** are supported.

You will need to use the HTTPS URL when using an access token and the SSH URL when using an SSH key to access your Git repository.

3. Create `stacks` and `config` branches in your `cycloid-onboarding` repository.

The easiest way is to do it via your git system portal, but if that is not possible, you can also do it with a shell like shown below (authentication is required prior to running these commands).

Commands to run

```
git clone cycloid-onboarding
cd cycloid-onboarding
git checkout --orphan stacks
touch .gitignore
git add .gitignore
git commit -m "Init stacks branch"
git push origin stacks
git checkout --orphan config
git add .gitignore
git commit -m "Init config branch"
git push origin config
```

## Save your git credentials[​](#save-your-git-credentials "Direct link to Save your git credentials")

### Option 1 - Using an Access Token[​](#option-1---using-an-access-token "Direct link to Option 1 - Using an Access Token")

1. From the left menu on the Cycloid console, click on **Security** ➔ **Credentials**, and then click the **Add Credential** button.
2. Fill in the new credential form with **git** as the name, **basic\_auth** as the type and paste your git user name and token like this:

![](/img/cookbook/git_token.png)

### Option 2 - Using an SSH key[​](#option-2---using-an-ssh-key "Direct link to Option 2 - Using an SSH key")

1. From the left menu on the Cycloid console, click on **Security** ➔ **Credentials**, and then click the **Add Credential** button.
2. Fill in the new credential form with **git** as the name, **ssh** as the type and paste your private key in the ssh\_key field like this:

![](/img/cookbook/git_ssh.png)

## Add your Catalog Repository[​](#add-your-catalog-repository "Direct link to Add your Catalog Repository")

info

Catalog Repositories store **repeatable automation templates** called **Stacks**, which constitute your Service Catalog.

A Stack can contain automation such as **Terraform, Ansible, Helm charts**, etc. a **StackForms** definition file to design user-friendly web forms as well as a pipeline.

The Stacks are version controlled via Git in **Catalog repositories**. Your Ops team maintains your Stacks according to a **GitOps approach**. They are the source of truth.

Cycloid Infra Import needs **read/write access** to the Catalog repository to push the newly generated Stacks. If you don’t need Infra Import, a **read access** to the Catalog repository is sufficient.

A Stack can be used across **many projects and environments** (aka. deployments).

1. From the left menu on the Cycloid console, click on **Stacks** ➔ **Catalog Repositories**, and then click the **Add Catalog Repository** button.
2. Fill in the new catalog repository form with a name, your Git repository url, select your **git** private key, and select the **stacks** branch, like this:

![](/img/cookbook/catalog_repo.png)

## Add your Config Repository[​](#add-your-config-repository "Direct link to Add your Config Repository")

info

When creating a project environment, a user can **customize pipeline and terraform variables using StackForms** according to your Stack design (cf. .forms.yml file). These parameter values are **version controlled** via Git in Config repositories. **Each environment config** will be saved in a Config repository in a **specific path**. In other words, Config repositories store the **desired state** of your deployed environments in a GitOps approach. They are the **source of truth**. Cycloid StackForms needs **read/write access** to the config repository to push the changes made by the users. The **pipelines** detect the config changes from the Git Config repository and **apply the modifications** to the infrastructure and applications during their lifecycle.

1. From the left menu on the Cycloid console, click on **Projects** ➔ **Config Repositories**, and then click the **Add Config Repository** button.
2. Fill in the new catalog repository form with a name, your Git repository url, select your **git** private key, select the **config** branch, and enable the Default switch like this:

![](/img/cookbook/config_repo.png)

You will need access to a Cycloid platform account

* The invitation email from Cycloid.

* Email of the users you would like to invite to your Cycloid test environment.

* A new and empty private Git repository from Github, Gitlab, Bitbucket, Azure DevOps, etc.

* An SSH key or an access token to read and write to your Git repository.

* An empty storage bucket or container to store your Terraform state files.

* Your cloud account credentials (or ability to create such credentials) with the following permissions:

  <!-- -->

  * permission to create compute instances and basic networking resources
  * permission to read and write on the above storage bucket or container
  * any other permission required by your custom automation in the PoC phase


---

# Organizations

## The concept of Organization[​](#the-concept-of-organization "Direct link to The concept of Organization")

The concept of Organization brings governance with Multi-Tenancy to your comapny.

Multi-tenancy allows multiple internal or external customers to use one SaaS or self-hosted platform, while RBAC helps to govern clouds, tools, automation & teams in each organization.

It also allow for predictable Total Cost of Ownership with simple subscription model per organization.


---

# Terraform backend

## Set up a Terraform backend[​](#set-up-a-terraform-backend "Direct link to Set up a Terraform backend")

info

Cycloid acts as an HTTP Terraform remote backend for the automation in the pipelines and stores the Terraform state files in a storage bucket or container behind the scenes.

Please follow the instructions for your preferred cloud provider: [AWS](#using-aws), [Azure](#using-azure) or [GCP](#using-gcp).

## Using AWS[​](#using-aws "Direct link to Using AWS")

### Create an S3 bucket[​](#create-an-s3-bucket "Direct link to Create an S3 bucket")

From the AWS console, go to the `S3` service and create a new S3 bucket.

Cycloid does not have other requirements. It is up to you to name the bucket, enable encryption, versioning or other options according to your preferences.

warning

Make sure your AWS credentials set up at the previous step have permission to read and write on this S3 bucket.

### Set up Terraform backend[​](#set-up-terraform-backend "Direct link to Set up Terraform backend")

1. From the Cycloid console, click on the organization menu in the top right corner of the page and then click on **Organization settings** item at the bottom of the menu.
2. In the **Settings** tab, scroll down to the **Terraform** section and click on the **Configure** button.
3. Select **AWS / S3 compatible** as the provider, select the cloud provider credential created in step 3, enter the region and the S3 bucket name created in the previous step, for example like this:

![](/img/cookbook/aws_terraform_backend.png)

## Using Azure[​](#using-azure "Direct link to Using Azure")

### Save storage account credentials[​](#save-storage-account-credentials "Direct link to Save storage account credentials")

1. From the Azure console, go to **Storage accounts** and create a new one (if you already have one you can use, ignore this step).
2. Go to the storage account and from the left-hand side menu, click on **Security + networking** ➔ **Access keys**. Copy the `key` field value from either `key1` or `key2`. **Put aside the credential for the next steps**.
3. From the left menu on the Cycloid console, click on **Security** ➔ **Credentials**, and then click the **Add Credential** button
4. Fill in the new credential form with **azure\_storage** as the name, **azure\_storage** as the type and then paste your Storage account name and key like this:

![](/img/cookbook/azure_storage_cred.png)

### Create an Azure Storage container[​](#create-an-azure-storage-container "Direct link to Create an Azure Storage container")

1. From the Azure console, go to the Storage account you previously created
2. From the left menu, click **Data storage** ➔ **Containers** and create a new container

### Set up Terraform backend[​](#set-up-terraform-backend-1 "Direct link to Set up Terraform backend")

1. From the Cycloid console, click on the organization menu in the top right corner of the page and then click on **Organization settings** item at the bottom of the menu.
2. In the **Settings** tab, scroll down to the **Terraform** section and click on the **Configure** button.
3. Select **Azure** as the provider, select the azure storage credential created in the previous step, and enter the container name created previously.

## Using GCP[​](#using-gcp "Direct link to Using GCP")

### Create a GCS bucket[​](#create-a-gcs-bucket "Direct link to Create a GCS bucket")

From the GCP console, go to the `Cloud Storage` service and create a new bucket.

Cycloid does not have other requirements. It is up to you to name the bucket, enable encryption, versioning or other options according to your preferences.

warning

Make sure your GCP credentials set up at the previous step have permission to read and write on this bucket.

### Set up Terraform backend[​](#set-up-terraform-backend-2 "Direct link to Set up Terraform backend")

1. From the Cycloid console, click on the organization menu in the top right corner of the page and then click on **Organization settings** item at the bottom of the menu.
2. In the **Settings** tab, scroll down to the **Terraform** section and click on the **Configure** button.
3. Select **GCP** as the provider, select the GCP credential created in the previous step, and enter the GCS bucket name created previously.


---

# Stack v4 migration guide

This guide is aimed toward stack maintainers. Cycloid released the Component layer feature that allows you and your users to instanciate multiple stacks in the same environment, enabling composability in you platform.

In order be able to use components, you need to update your stacks to `version: 4` this guide will walk you through all the steps required to easily migrate your stacks.

### Why did we increment the stack versions ?

Stacks before v3 don't use the new special variable `component` to differenciate config paths in the `.cycloid.yml`.

The standard way for most stacks in versions 1 to 3 to build config path was this convention:

.cycloid.yaml

```
config:
  use-case:
    name: 'My Use case'
    pipeline:
      pipeline:
        path: 'pipeline/pipeline.yml'
      variables:
        path: 'pipeline/variables.sample.yml'
        destination: '($ .project $)/pipeline/($ .env $)/variables.yml'
```

This causes an issue for using component since most stacks uses the same path that don't include `($ .component $)`, creating two components with legacy stacks in the same env will lead to config overlap and unexpected behavior !

Thus we incremented the version and added a check inside Cycloid. User can't create more than one component with a stack v1-3 in the same environment.

You can however add any number of components using stacks v4 alongside one v1-3 stack in the same environment.

This allows you to use the old stack the old way (one stack, one env) and migrate to components gradually.

We recommend that you migrate all your stacks to **v4**, as v1-3 stacks will be *deprecated* in the future.

## Pre-requisites[​](#pre-requisites "Direct link to Pre-requisites")

First you need to think about you strategy for migrating stacks, you can either:

1. Update stacks in-place
2. Fork the stacks in the same catalog repository
3. Fork the stacks in another catalog repository

If you go for the third strategy, you will have to create another catalog repository and add it to your organization.

Use [our existing documentation on the subject](/reference/config-and-catalog-repository/.md).

### Strategy[​](#strategy "Direct link to Strategy")

You will have to plan how to migrate you stacks in order to avoid disruption for you users.

We propose you 3 ways to do it. But depending on your use-case you can think of a strategy that fits your organizations.

Feel free to [ask our team via our support page](https://support.cycloid.io) for advices on how to manage this migration.

#### Update stacks in-place[​](#update-stacks-in-place "Direct link to Update stacks in-place")

This strategy is the most simple but is also the most dangerous. Updating the stack in-place means that every user can get errors or issues while you migrate.

Only do it if you are aware of the impact on your users.

#### Fork the stacks in the same catalog repository[​](#fork-the-stacks-in-the-same-catalog-repository "Direct link to Fork the stacks in the same catalog repository")

You can copy a current stack (for example `stack-a`) in the same catalog repository.

In that case you will have to rename the canonical of the stack in the `.cycloid.yml` to avoid canonical collision. (we recommend that you also rename the stack to avoid confusion in the Cycloid Console.).

This approach is safer and allows you to ensure that existing components will still work with the old code.

#### Fork the stacks in another catalog repository[​](#fork-the-stacks-in-another-catalog-repository "Direct link to Fork the stacks in another catalog repository")

This is similar to the above, but forking the config repo can enable your team to work on stacks from a dedicated testing org with its dedicated catalog, and release stacks when you are ready.

No matter which strategy you choose, the migration process for a stack is the same.

### Anticipate impact on terraform resources[​](#anticipate-impact-on-terraform-resources "Direct link to Anticipate impact on terraform resources")

While updating your stacks, you will add the `($ .component $)` canonical in your code, most of the time, `project`, `env` and `component` will be used to differenciate and identify resources.

Updating names and resources tags could lead to resources re-creation in terraform, or alter name / tags of existing resources.

Evaluate those changes before migrating. If adding the `component` canonical could break existing infrastructure, we recomment to fork you stacks (using the 2nd or 3rd strategy described above) to keep old envs working as expected.

Also, if you let terraform apply change automatically on stack update, disable the trigger in the pipeline to avoid unintended breaking changes.

These changes can extend beyond terraform, it's up to your team to assess those changes.

Again, feel free to [ask our support team](https://support.cycloid.io) to help you in this transition.

## How to migrate[​](#how-to-migrate "Direct link to How to migrate")

### A. Config path in `.cycloid.yml`[​](#a-config-path-in-cycloidyml "Direct link to a-config-path-in-cycloidyml")

First thing to attend is the config path of the `.cycloid.yml`.

Refresher

The config path in the `.cycloid.yml` is defined by the `destination` key in each use\_case.

It reference the path where the config will be writed in the config repository when a user instanciate the stack in a component.

.cycloid.yml

```
---
version: '3'
name: 'My Stack'
canonical: 'my-stack'
author: 'Cycloid'
config:
  # Define use-cases
  default:
    name: 'my default use-case'
    pipeline:
      pipeline:
        path: 'pipeline/pipeline.yml'
      variables:
        path: 'pipeline/variables.sample.yml'
        # The config path where the variables will be writed in the config repo
        # for this usecase:
        destination: '($ .project $)/pipeline/($ .env $)/variables.yml'
```

See the [stack concept guide](/reference/stacks/concepts/stack-concept.md) if you need a refresher.

To avoid config collision using components, you need to add the `($ .component $)` special var in the `destination` attribute of all you use\_cases.

You need to put each component in a separate folder, notably for terraform.

Our new convention will be to use `($ .org $)/($ .project $)/($ .env $)/($ .component $)/` as a base path for each components.

That will organize your configuration in the same pattern as the UI, like this:

```
.
├── org1
│   ├── project-a
│   │   ├── dev
│   │   │   ├── component-1/pipeline/... // config files...
│   │   │   ├── component-1/terraform/...
│   │   ├── prod
│   │   │   ├── component-1
│   │   └── staging
│   │       ├── component-1
│   │       └── component-2
│   └── project-b
│       ├── prod
│       │   ├── component-1
│       │   └── component-2
├── org2
│   ├── project-a
│   │   ├── dev
│   │   │   ├── component-1
...
```

tip

We added a cycloid special variable named `config_path` to simplify the use of the default config path convention.

That means that using `($ .config_root $)` will be the same as putting `($ .org $)/($ .project $)/($ .env $)/($ .component $)` in your configuration.

We updated our special variables to be more consistent, see [the whole list here](/reference/stacks/concepts/templating.md#special-variables).

note

You can implement the path that fits your usecase, the bare minimum would be to use the `project`, `environment` and `component` special vars to avoid collision between components.

If you use another pattern, or if you deal with collisions in another way (maybe by using different config repo per project or so) you are free to do so. Cycloid won't enforce anything but requiring your stack to update to v4 if you want to use components.

We will update the version later in this guide, for now, keep it in the current state.

To take the previous example, here would be the updated `.cycloid.yml`:

.cycloid.yml

```
---
version: '3'
name: 'My Stack'
canonical: 'my-stack'
author: 'Cycloid'
config:
  use_case:
    name: 'my default use-case'
    pipeline:
      pipeline:
        path: 'pipeline/pipeline.yml'
      variables:
        path: 'pipeline/variables.sample.yml'
-       destination: '($ .project $)/pipeline/($ .env $)/variables.yml'
+       destination: '($ .org $)/($ .project $)/($ .env $)/($ .component $)/pipeline/variables.yml'
```

Or better, using our `config_path` special var:

.cycloid.yml

```
---
version: '3'
name: 'My Stack'
canonical: 'my-stack'
author: 'Cycloid'
config:
  use_case:
    name: 'my default use-case'
    pipeline:
      pipeline:
        path: 'pipeline/pipeline.yml'
      variables:
        path: 'pipeline/variables.sample.yml'
+       destination: '($ .config_root $)/pipeline/variables.yml'
```

note

Note the added `pipeline/` folder at the end. We will separate each technology per folder. Also, we changed the minimum characters length on usecases key identifier, it goes from 2 to 3.

We will do the same for terraform, here is an extended example of a stack with multiple use cases and terraform paths:

.cycloid.yml

```
---
version: '3'
name: 'My App deployment'
canonical: 'my-app'
author: 'Cycloid'
config:
  deploy-k8s:
    name: 'Deploy myApp on k8s'
    pipeline:
      pipeline:
        path: 'pipeline/deploy-k8s.pipeline.yml' # each use case has its own pipeline and variable.sample file
      variables:
        path: 'pipeline/deploy-k8s.variable.sample.yml'
        destination: '($ .config_root $)/pipeline/variables.yml'
    terraform:
      main:
        path: 'terraform/deploy-vm.main.tf.sample'
        destination: '($ .config_root $)/terraform/main.tf'
  deploy-vm:
    name: 'Deploy myApp in a VM'
    pipeline:
      pipeline:
        path: 'pipeline/deploy-vm.pipeline.yml'
      variables:
        path: 'pipeline/deploy-vm.variable.sample.yml'
        destination: '($ .config_root $)/pipeline/variables.yml'
    ansible: # For ansible too
      web:
        path: 'ansible/environments/inventory.yml.sample'
        destination: '($ .config_root $)/ansible/inventory.yml'
    terraform:
      main:
        path: 'terraform/deploy-vm.main.tf.sample'
        destination: '($ .config_root $)/terraform/main.tf'
```

tip

Keep the `version: 3`, we will update it at the end when the stack is ready to be used as a component.

We still have work to do to make it compatible at this stage.

### B. Update the pipeline[​](#b-update-the-pipeline "Direct link to B. Update the pipeline")

The configuration is pull via the pipeline using the [`git` concourse resource](https://github.com/concourse/git-resource?tab=readme-ov-file#source-configuration) and then merged using our [merge stack and config script](/reference/ci-cd-pipelines/concepts/cycloid-toolkit.md#stack-concept-with-merge-stack-and-config).

So you need to update all the git resource that watch and fetch the config to use the new `destination` path in the `.cycloid.yml`.

We will use the following pipeline as an example:

pipeline.yml

```
---
# This is an usual pipeline using terraform before stack v4 update
definitions:
  tasks:
    - &task-merge-stack-and-config
      task: merge-stack-and-config
      config:
        platform: linux
        image_resource:
          type: registry-image
          source:
            repository: cycloid/cycloid-toolkit
            tag: latest
        run:
          path: /usr/bin/merge-stack-and-config
        inputs:
        - name: stack
          path: "stack"
        - name: config
          path: "config"
        outputs:
        - name: merged_stack
          path: "merged_stack"

      params:
        CONFIG_PATH:  '($ .project $)/terraform/($ .env $)/terraform/'
        STACK_PATH: '($ .stack_path $)/terraform'
        MERGE_OUTPUT_PATH: "merged_stack/"

resource_types:
- name: terraform
  type: registry-image
  source:
    repository: cycloid/terraform-resource
    tag: '1.8.2'

resources:
- name: tfstate
  type: terraform
  icon: terraform
  source:
    backend_type: http
    backend_config:
      address: '($ .api_url $)/inventory?jwt=($ .inventory_jwt $)'
      skip_cert_verification: true
    env_name: ($ .env $)

- name: stack
  type: git
  icon: github-circle
  source:
    uri: ($ .scs_url $)
    branch: ($ .scs_branch $)
    private_key: ((($ .scs_cred_path $).ssh_key))
    paths:
      - ($ .stack_path $)/terraform/*

- name: config # this is where we declare the resource that will fetch the config
  type: git
  icon: github-circle
  source:
    uri: ($ .cr_url $)
    branch: ($ .cr_branch $)
    private_key: ((($ .cr_cred_path $).ssh_key))
    paths:
    - '/($ .project $)/terraform/($ .env $)/*'

# Define jobs that form the pipeline
jobs:
  - name: terraform-plan
    serial: true
    serial_groups: [terraform]
    max_in_flight: 1
    build_logs_to_retain: 10
    plan:
    - do:
      - get: stack
        trigger: true
      - get: config
        trigger: true
      - *task-merge-stack-and-config
      - put: tfstate
        params:
          plan_only: true
          terraform_source: merged_stack/

  - name: terraform-apply
    serial: true
    serial_groups: [terraform]
    build_logs_to_retain: 10
    plan:
    - do:
      - get: stack
        trigger: false
        passed:
          - terraform-plan
      - get: config
        trigger: false
        passed:
          - terraform-plan
      - get: tfstate
        trigger: false
        passed:
          - terraform-plan
      - *task-merge-stack-and-config
      - put: tfstate
        params:
          plan_run: true
          terraform_source: merged_stack/

  - name: terraform-destroy
    serial: true
    serial_groups: [terraform]
    build_logs_to_retain: 10
    plan:
    - do:
      - get: stack
        trigger: false
      - get: config
        trigger: false
      - *task-merge-stack-and-config
      - put: tfstate
        params:
          action: destroy
          terraform_source: merged_stack/
        get_params:
          action: destroy

groups:
- name: overview
  jobs:
  - terraform-plan
  - terraform-apply
- name: destroy
  jobs:
  - terraform-destroy
```

You will have to update:

* The `CONFIG_PATH` of the `merge-stack-and-config`.
* The `source.paths` attribute in the git resource that manage the config. // TODO

pipeline.yml

```
---
# This is an usual pipeline using terraform before stack v4 update
definitions:
  tasks:
    # Merge stack and config anchor to use later.
    - &task-merge-stack-and-config
      task: merge-stack-and-config
      config:
        platform: linux
        image_resource:
          type: registry-image
          source:
            repository: cycloid/cycloid-toolkit
            tag: latest
        run:
          path: /usr/bin/merge-stack-and-config
        inputs:
        - name: stack
          path: "stack"
        - name: config
          path: "config"
        outputs:
        - name: merged_stack
          path: "merged_stack"

      params:
        # Update the CONFIG_PATH of the merge-stack-and-config
        CONFIG_PATH:  '($ .config_root $)/terraform/'
        STACK_PATH: '($ .stack_path $)/terraform'
        MERGE_OUTPUT_PATH: "merged_stack/"

resource_types:
# Ellipsis...
- name: config # this is where we declare the resource that will fetch the config
  type: git
  icon: github-circle
  source:
    uri: ($ .cr_url $)
    branch: ($ .cr_branch $)
    private_key: ((($ .cr_cred_path $).ssh_key))
    # Update the path that the resource will watch and clone
    paths:
    - '($ .config_root $)/terraform/*'

# The rest of this example file don't need to be updated
```

tip

At this stage, you will have to check all the reference to the config path and update it.

Also, anything you do in your script that require separation between component will need to handle get the component canonical using the `($ .component $)` or `($ .config_root $)` var.

### C. Update the terraform code[​](#c-update-the-terraform-code "Direct link to C. Update the terraform code")

The terraform code is the more tricky part.

warning

Altering resources attributes like names, id, tags and other metadata *could* end up re-creating resources depending on the provider.

Be careful on stacks that will automatically trigger the terraform apply in your pipeline.

You will need to add the `component` variable in all your modules. Usually they already uses `org`, `project`, `env`

variables.tf

```
variable "org" {}
variable "project" {}
variable "env" {}
variable "component" {}
```

You can inject them in the modules by directly using the special vars in the module call inside you `main.tf.sample` defined in your `.cycloid.yml`.

main.tf.sample

```
module "my_module" {
  source    = "./some/module"

  org       = "($ .org $)"
  project   = "($ .project $)"
  env       = "($ .env $)"
  component = "($ .component $)"
}
```

Then you will need to identify what resources uses the `org`, `project`, `env` variables to get identified in your code and add the `component` variable.

### D. Update Ansible code[​](#d-update-ansible-code "Direct link to D. Update Ansible code")

Following the upgrade to version 4, which introduced the component layer as shown above, this new layer has been added to Terraform. It is typically used as an additional tag on your cloud resources.

With this addition, we will also pass the component canonical name to Ansible. This allows you to use it within your Ansible code, as well as in the Ansible inventory for filtering by this additional tag.

To do this, add the `component` variable to the `EXTRA_VARS` list in your pipeline template:

pipeline.yml

```
        params:
          EXTRA_VARS:
            organization: ((organization))
            project: ((project))
            env: ((environment))
            component: ((component))
```

Here is an example of a host filter using AWS dynamic inventory, including the component tag:

ansible/main.yaml

```
- hosts: :&tag_org_{{ organization }}:&tag_project_{{ project }}:&tag_env_{{ env }}:&tag_component_{{ component }}
```

### E. Update the version[​](#e-update-the-version "Direct link to E. Update the version")

Once you have updated all your code, you can now increment the `.cycloid.yml` version and test your changes:

.cycloid.yml

```
---
version: '4'
name: 'My Stack'
canonical: 'my-stack'
author: 'Cycloid'
config:
  use_case:
    name: 'my default use-case'
    pipeline:
      pipeline:
        path: 'pipeline/pipeline.yml'
      variables:
        path: 'pipeline/variables.sample.yml'
        destination: '($ .config_root $)/pipeline/variables.yml'
```

## Examples[​](#examples "Direct link to Examples")

To help you understand the changes, here is a list of public stacks we have that migrated to components, you can check the diff to better grasp how to do it:


---

# Welcome to Cycloid

Cycloid is an [Engineering platform](https://www.gartner.com/en/infrastructure-and-it-operations-leaders/topics/platform-engineering). It’s designed to facilitate developer and end-user experience, eliminate team silos and accelerate time-to-market speed by providing modules around Governance, Deployment, Operations, FinOps, and GreenOps.

Whether or not you already have an internal platform team, Git-based and lock-free Cycloid will easily complement your existing ecosystem and streamline the software delivery process.

Before you dive in and see what we do here at Cycloid, here's a quick demo video of what to expect.

[YouTube video player](https://www.youtube.com/embed/eQVNorBg3jg?si=q5-ViOyFZUCOmSrp)

### A Self service developer portal[​](#a-self-service-developer-portal "Direct link to A Self service developer portal")

Cycloid's self-service portal enables developers to manage infrastructure and automation without requiring a consistent team intervention.

It reduces repetitive tasks, improves user experience, and accelerates delivery by offering an intuitive, user-friendly interface.

Through a set of tools the portal makes cloud infrastructure infrastructure management more easy and acessible while automating routine tasks.

This ensure that operations teams can focus on higher-value projects, enhancing productivity and business agility.

![Stack-catalog](/assets/images/stacks-catalog-46dd4dfe19e06b48e1ca806824f4b99c.png)

### Infra as Code (IaC)[​](#infra-as-code-iac "Direct link to Infra as Code (IaC)")

Cycloid leverages Infrastructure as Code (IaC) to automate and manage infrastructure efficiently.

By using tools like Infra Import, Cycloid seamlessly transitions existing resources into code, while InfraPolicies enforce governance and security.

This ensures consistent, reproducible configurations, enhancing security and operational efficiency and fosters a more efficient infrastructure management process.

![Stackforms](/assets/images/forms-create-db8375928fa1d719b72992d5329ae757.png)

### FinOps and GreenOps[​](#finops-and-greenops "Direct link to FinOps and GreenOps")

Cycloid's FinOps and GreenOps tools provide a clear way to help organizations achieve financial efficiency and sustainability goals in terms of cloud usage.

It provides tools to predict the cost of infrastructure changes, centrally track and visualize your cloud expenses and also estimate the impact of your cloud infrastructure carbon footprint.

![CCM-Dashboard](/assets/images/ccm-dashboard-3c7b995fb8cadefb7e302e6d0cd0ef41.png)

tip

This current section describe the different features of Cycloid.

If you want to dive straigt into the technical documentation, visit the reference:

[Go to the reference documentation](/reference.md)


---

# Asset Inventory

<!-- -->

Asset Inventory provides one place to easily view, analyze, and understand all your assets across projects and environments.

Resources within the Cycloid Inventory can be provisioned via API calls or automatically through the Cycloid Terraform HTTP backend.

All resources generated by your projects should be present here, complete with comprehensive details. For instance, if a project creates a cloud instance, it should be listed in the resources inventory, showcasing essential information such as IP address, size, and more.

Moreover, utilizing the asset inventory in conjunction with the Cycloid Terraform HTTP backend offers automation and additional features, including [InfraView](/reference/infraview/.md) for projects utilizing Terraform.

![Inventory](/assets/images/inventory-c355060d9de8441d66cdd593ca073ed9.png)

[Go to the Asset Inventory documentation](/reference/inventory/.md#introduction)


---

# CI/CD Pipelines

<!-- -->

Cycloid CI/CD enables the creation of immutable pipelines, ensuring that each pipeline job build is based on a defined set of external resources and dependencies. This eliminates issues related to unpredictable changes in resources, providing a stable and reproducible build environment.

Our pipeline engine orchestrate an entire workflow through a visual interface.

You can use it to build an application, create an infrastructure, deploy an application, interact with monitoring tool, and all others steps you could imagine...

Our pipeline engine is based on the open-source [Concourse CI software](https://github.com/concourse/concourse).

![Cycloid Pipeline Sample](/assets/images/cycloid-pipeline-sample-7b0e8505ec3423e81d1db46305d79d5f.png)

Cycloid CI/CD enables the creation of immutable pipelines, ensuring that each pipeline job build is based on a defined set of external resources and dependencies.

This eliminates issues related to unpredictable changes in resources, providing a stable and reproducible build environment.

## How does it work?[​](#how-does-it-work "Direct link to How does it work?")

Our pipelines are the core of a stack. That is, each stack contains a template of a pipeline and a sample of variables.

A pipeline describes the workflow of a stack, e.g. how to create an application and how to automate and orchestrate the deployment of new releases, as you can see in the picture bellow.

![pipelines](/assets/images/pipelines-c0aa9c43aca90df96882d049b088c147.png)

So when creating a stack, you have to describe a YAML template describing the pipeline and a sample of variables on how to configure it.

Then, when you create a project from a stack, the template is read by Cycloid to create a running pipeline.

[Go to the CI/CD Pipelines documentation](/reference/ci-cd-pipelines/.md#introduction)


---

# Cloud Carbon Footprint

Cycloid's Cloud Carbon Footprint tool is designed to measure and analyze the environmental impact of cloud infrastructure deployments.

It enables organizations to assess and optimize their carbon footprint across cloud services.

Cloud Carbon Footprint collects data on resource usage from cloud providers and calculates the associated carbon emissions.

## How does it work?[​](#how-does-it-work "Direct link to How does it work?")

The feature is embedded within [Cloud Cost Management](/reference/cloud-cost-management/.md "Cloud Cost Management").

So it will convert your cloud data usage into cloud emissions based on a public opensource [carbon footprint calculator](https://www.cloudcarbonfootprint.org/docs/methodology/).

Then it tranforms that data in a bunch of different grafical and visual representations so that you can have a better more centralized view of it.

You'll simply will have to configure the required accesses and tools within your cloud provider.

And then the tool will take of the rest will take care of the rest.

[YouTube video player](https://www.youtube.com/embed/NtX4c5CvetQ?si=kocKCwPBQOfPaFFN)

[Go to the Cloud Carbon Footprint documentation](/reference/cloud-carbon-footprint/.md)


---

# Cloud Cost Management

Cycloid's Cloud Cost Management tool empowers organizations to effectively monitor and visualize costs associated with cloud infrastructure deployments.

It provides comprehensive insights and tools to improve the control of your cloud spending.

## How does it work?[​](#how-does-it-work "Direct link to How does it work?")

The tool starts by retrieving your cloud data usage from your cloud provider.

Then it tranforms that data in a bunch of differnt grafical and visual representations so that you can have a better more centralized view of it.

You'll simply will have to configure the required accesses and tools within your cloud provider.

And then cloud cost management will take care of the rest.

![ccm](/assets/images/ccm-dashboard-3c7b995fb8cadefb7e302e6d0cd0ef41.png)

## More details[​](#more-details "Direct link to More details")

For more detailed use cases and information, visit our documentation page on [Cloud Cost Management](/reference/cloud-cost-management/.md "Cloud Cost Management") doc pages.


---

# Connectivity with with identity providers

Cycloid can be used with different user authentication methods.

It acheieves this, by supporting integration major identity providers such as OpenID, SAMLv2, and AzureAD.

This connectivity allows organizations to leverage existing identity management systems for user authentication, enhancing security and simplifying user management.

## How does it work?[​](#how-does-it-work "Direct link to How does it work?")

Cycloid connects to identity providers, enabling users to log in using their existing credentials.

![login-idp](/assets/images/login-idp-90cd094e2c6e333cba4ada8041b4fd91.png)

[Go to the Identity Providers documentation](/reference/organizations/concepts/authentication.md)


---

# Cost Estimation

<!-- -->

Cloud Cost Management (CCM) is a feature that enables you to analyze in detail the costs generated by your cloud infrastructure.

It offers an intuitive graphical interface that helps anyone within your organization visualize, manage, and explore cloud expenses across multiple providers with ease.

![](/img/ccm/ccm-dashboard.png)

<br />

In a nutshell, this tool begins by retrieving data from your cloud providers, allowing you to visualize and analyze it through an intuitive dashboard.

In the following sections, you'll learn how to get started with Cloud Cost Management and explore all of its key features.

note

Within this feature, our [Cloud Carbon Footprint](/reference/cloud-carbon-footprint/.md "Cloud Carbon Footprint") tool is integrated, allowing you to visualize your cloud carbon footprint data alongside your cost data. Because of this integration, it is not possible to opt out of carbon footprint data when using CCM.

Cost Estimation provides a way for organisations to accurately forecast and predict their cloud infrastructure expenditures.

This tool is based on our opensource tool [terracost](https://github.com/cycloidio/terracost), that allows to estimate costs based on the terraform resources configuration.

It provides a simple, transparent and more accessible way to perform budgeting and financial planning processes.

## How does it work?[​](#how-does-it-work "Direct link to How does it work?")

When a project is being configured, using Stackforms, the predicted cost will be estimated and displayed before project creation.

This estimation is based on the terraform configuration of the project

![cost-estimation](/assets/images/cost-estimation-f366d48482853b95a2f3c7b563e82fc3.png)

[Go to the Cost Estimation documentation](/reference/cloud-cost-management/.md#pre-requisites)


---

# Credential Management

<!-- -->

Cycloid credential manager securly stores, accesses, and distributes secrets like API keys, cloud provider credentials, TLS certificates, SSH keys and more.

We have created an abstraction on top of open sourced [hashicorp vault](https://www.hashicorp.com/products/vault "Hashicorp vault") make the secret management simple, easy and secure for your teams.

Credentials can be used inside pipelines to provisions secret values to all technologies you use (terraform, ansible, and more...).

Cycloid provides robust credential management, allowing users to securely manage and store various types of credentials.

This credentials include cloud provider keys, SSH keys, and API tokens.

This ensures that sensitive information is handled securely and efficiently within the platform.

## How does it work?[​](#how-does-it-work "Direct link to How does it work?")

Users can create and manage credentials within Cycloid, in accordance to their permissions.

Credentials are stored securely using an Haschicorp Vault and can be linked to projects or resources as needed.

![Create credential form](/assets/images/credentials-6f0673076207800d1e47ddb1070df056.png)

[Go to the Credential Management documentation](/reference/credentials/quickstart.md)


---

# InfraImport

[YouTube video player](https://www.youtube.com/embed/X8P6Sd-5wAM?si=7D0k8UzYLQyJQ6M1)

<!-- -->

Infra Import is an infrastructure-as-code generator based on [TerraCognita](/reference/oss/terracognita.md), our open source CLI tool. Designed to streamline your infrastructure management. With this tool, you can effortlessly generate reverse Terraform code from existing manually-deployed infrastructure

Connect it to your manually-deployed cloud infrastructure and Infra Import will create your [Stacks](/reference/stacks/concepts/stack-concept.md) and push them to the predefined [Catalog repository](/reference/config-and-catalog-repository/.md).

Our main use cases involve taking over an existing infrastructure:

* Consider a scenario where an individual or a team creates a proof-of-concept (POC) infrastructure. After successfully validating the POC, the infrastructure team aims to transform it into a production template that can be reused for deploying other applications.
* Alternatively, over time, an infrastructure may have already been deployed and used in production. The infrastructure team may now seek to effortlessly migrate it to infrastructure-as-code.

This is where Infra Import comes into play, simplifying the process by automatically generating infrastructure-as-code and state files for a running infrastructure.

Infra Import is Cycloid's tool for automating infrastructure management through TerraCognita, our opensource tool.

It seamlessly converts existing and manually-deployed cloud infrastructure into Terraform code.

## How does it work?[​](#how-does-it-work "Direct link to How does it work?")

You import your current infrastructure by creating a new project based on a specific set of objects selected to import from your cloud account.

Then InfraImport connects to your cloud provider and pushes the generated Terraform code to a Git repository for easy access and version control.

You only need to setup the necessary access permisions on your cloud provider and tag resources in your cloud environment to optimize the import process.

And you're good to go!

## More details[​](#more-details "Direct link to More details")

For more detailed use cases and information, visit our documentation page on [infra import](/reference/infra-import/.md) doc pages.

[Go to the InfraImport documentation](/reference/infra-import/quickstart.md)


---

# Infrapolicies

Infrastructure Policies (InfraPolicy) are an implementation of Policy as Code.

The idea is to enforce fine-grained control over changes across an organization's infrastructures while simultaneously defining validation rules.

This can be used for example to enforce some security or management guidelines.

## How does it work?[​](#how-does-it-work "Direct link to How does it work?")

Initally you need to create or select a set of policies, based on the [Open Policy Agent](https://www.openpolicyagent.org/docs/latest) engine, with a severity degree (advisory, warning and critical)

And then apply that policy using a validating resource before any infrascture change in the pipeline.

![infrapolicy](/assets/images/infrapolicy-11a87ed1fef8f00ee9137dcd6d49fc57.png)


---

# Infraview

<!-- -->

InfraView, powered by [Inframap](https://github.com/cycloidio/inframap/), is a centralized graphical tool designed to provide a comprehensive representation of your infrastructure. It offers unparalleled visibility into your cloud resources and facilitates seamless collaboration across teams.

InfraView leverages Terraform's TFState file to gather information about your infrastructure. By analyzing this file, it creates a visual representation that accurately reflects the state of your cloud environment.

![](/img/overview_populated-diagram.png)

**Key Features:**

1. **Interactive Schema:** The schema generated by InfraView is interactive, allowing users to click on individual resources to access detailed information such as IP addresses, VM sizes, and other relevant details.

2. **Graphical Representation:** InfraView offers a visual depiction of your cloud infrastructure, making it easier to understand complex architectures and relationships between resources.

3. **Collaboration:** InfraView acts as a bridge between different teams involved in managing your infrastructure. By providing a centralized platform for viewing and understanding the infrastructure

[Go to the Infraview documentation](/reference/infraview/.md#introduction)


---

# Logs and Events

Cycloid's Events and Logs tools allow for a quick and simple way to understand what is happening across the cycloid projects.

This unified approach helps teams monitor activities, respond to incidents, and troubleshoot effectively.

Events allow to centraly obtain details about what happened across the different project pipelines.

For example detailying what pipeline whas triggered, by whom and its status

The Logs feature, on the other hand, allow to aggregates log data from servers, applications, and cloud services, whitin a project

## How does it work?[​](#how-does-it-work "Direct link to How does it work?")

### Logs[​](#logs "Direct link to Logs")

To use logs in a project, you'll have to first send the logs you require to an elasticSearch or to AWS cloudwatch, the devops team can help you with this.

Then in the log tab of the project configure a backend to be able to retrieve those logs.

This usually entails specifying a credential and an endpoint to access them.

And you're good to go.

![logs](/assets/images/logs-b126934699514648443bae8a3e5cb74f.png)

### Events[​](#events "Direct link to Events")

To check the events you can go to oberservability tab on the console, to check all events of all the projects.

You can also add custom events to your pipelines, by adding a special pipeline configuration.

![events](/assets/images/events-9401e1c38cd8565af918f86b57f2f6b7.png)


---

# Organizations

An organization represents the highest entity level within cycloid.

That is, it serves as the foundation for managing all resources, including credentials, teams, and projects.

Each user must belong to at least one organization to perform any actions within Cycloid.

![org-switch](/assets/images/organizations-switch-e8b219d267fc6768301b9469fef584c0.png)

## How does it work?[​](#how-does-it-work "Direct link to How does it work?")

When you subscribe to cycloid an organization is created for you, associated with a specific license in accordance to your subscription access rigths.

You can then create sub-organizations and associate different users as you see fit easily within the console.

## More details[​](#more-details "Direct link to More details")

For more detailed use cases and information, visit our documentation page on [organizations](/reference/organizations/.md "Cycloid concepts: organization") doc pages.

[Go to the Organizations documentation](/reference/organizations/.md)


---

# Permissions and Roles

Cycloid's permissions system ensures secure access control within an organization.

It supports Role-Based Access Control (RBAC), allowing precise permissions management for users and groups based on their roles.

Permissions are assigned at the organization, project, and resource levels, providing granular control over actions users can perform.

## How does it work?[​](#how-does-it-work "Direct link to How does it work?")

Users are assigned roles that define their access and actions within Cycloid, at organization creation, based on your requirements and a set of pre-existing roles.

Administrators can customize roles and permissions to fit organizational needs, ensuring that users only access resources necessary for their tasks.

![Policies](/assets/images/policies-bf07db4101bdebcd13c2b08c01e346c6.png)

This structured approach enhances security and operational efficiency.

[Go to the Permissions documentation](/reference/organizations/concepts/permissions.md)


---

# SaaS vs On-premise

The choice between a SaaS or an On-premise approach to deploy cycloid, will always depend on your business requirements and your subcription.

There's pros and cons to both aproach, but the choice is up to you to decide which one to chose.

Depending on the approach you chose, different steps can be done to curretly setup cycloid console.

* If you use **SaaS aproach**: the cycloid team will create an organization with a specific license and provide you access to it.

* If you use **Onprem aproach**: there's 2 possibilites. You can install within a K8s cluster (using our helm chart) or install in a VM or group of VMs.

In any of the cases the cycloid devops team will always assist and guide you during the all setup procedure, until your platform is up and running 😉.

[Go to the Dedicated platform documentation](/reference/dedicated-platform/.md)


---

# StackForms

[YouTube video player](https://www.youtube.com/embed/KNa_s-QB6S0?si=5YorOeAObNUMNmg3)

<!-- -->

In Cycloid, a project's configuration can be exposed to users within a text editor or within a user-generated interface using StackForms.

StackForms provides a graphical interface to offer much better control over projects' creation or update.

For a stack user, it provides a visual way to configure a stack, displaying all parameters with associated descriptions split into sections and groups. On top of that the variable can benefit from extra then definitions: required/optional, description, values range/input, default value, etc. By doing so it makes it easier for users to understand and provide the appropriate configuration.

StackForms is compatible with Cycloid components, as special widgets allow users to select their own Credentials, Config repositories, etc. And also work with TerraCost to display in live an estimated cost of an infrastructure based on selected parameters!

Once the configuration is saved/updated, it is directly written in your project's config repository.

![Stackforms-demo](/assets/images/stackforms-demo-0842f6e99942b6ff6ccf02aa12fc1c4f.gif)

## List of main benefits[​](#list-of-main-benefits "Direct link to List of main benefits")

Here is a list summarizing the main benefit of using such feature.

1. Nice visual interface
2. Support of a wide range of types and widgets
3. Improved control on which variables to expose
4. Capacity to make the variable require or not - and/or have default values
5. Enforce limitations of values (range, list of values)
6. Basic template capacities for variables (linked to organization, projects, etc)
7. Easier access to Cycloid's entities (credential, config repositories, etc)
8. Capacity to run a cost estimation of the project
9. Centralization of variables definition
10. Get dynamic values from the Inventory
11. ...and many more to come!

StackForms allows users to configure projects through a graphical interface.

This interface enhances control over project creation and updating by displaying all parameters with corresponding descriptions, organized into sections and groups.

[Go to Stackforms documentation](/reference/stackforms/introduction.md)


---

# Stacks

[YouTube video player](https://www.youtube.com/embed/vgBoRe0L840?si=sEXasqKcAXR9v1Mh)

<!-- -->

In Cycloid, a stack refers to our primary automation concept.

A stack describes a generic infrastructure, service, or workflow using the principles of GitOps and Infrastructure as Code (IaC). This results in code stored within a Git repository.

In technical terms, a stack serves as a template that can be used repeatedly to obtain the described infrastructure or services. Additionally, it provides a means to customize parameters each time it is used.

Stacks can be shared with all users as an available list of "services"

![stack-list](/assets/images/stack-list-8c14deb77cf0b2a92e7cab5de0a23068.png)

**Who would use it?**

There are primarily two types of individuals who would be interested in stacks: users and maintainers.

Here's a concrete use case to illustrate its utility:

Imagine a company with two distinct teams: the "infra" team, responsible for managing infrastructure and servers, and the "app" team, responsible for developing and testing applications.

The infra team's responsibility is to ensure that all servers, networks, and other infrastructure components adhere to standardized patterns and best practices. Meanwhile, the app team focuses on developing and testing applications. To facilitate proper testing, the app team often requires temporary infrastructure to deploy new application releases and conduct tests.

The infra team aims to streamline the process of provisioning infrastructure, enabling the app team to work autonomously. However, they also need to maintain governance and control over access and resources used by the app team.

This is where stacks come into play. The infra team can create stacks that describe the servers and infrastructure required by the app team. The app team can then utilize these predefined stacks to deploy temporary infrastructure with minimal effort.

In this scenario, the infra team serves as stack maintainers, while the app team acts as stack users.

![stack-concept-users-kind](/assets/images/stack-concept-users-kind-b3cd431bb761851023349c8689d9d070.png)

Consider scaling this concept to a larger context, where you can describe various types of infrastructure, workflows, or service deployments. You can provide these predefined stacks as part of a catalog available to all users within the organization.

Keep in mind that use cases are not limited to that; we have plenty of other examples in our documentation to illustrate what you could actually do.

[Go to the Stacks documentation](/reference/stacks/.md#introduction)


---

# Workers

A key important component to understand of cycloid architecture are the cycloid workers, based on [concourse workers](https://concourse-ci.org/internals.html#architecture-worker "Concourse Worker").

They will run the different pipelines of your system, by running a set of containers resources for each of these pipelines.

And so they represent a vital part of cycloid, since without them nothing works.

No matter if you opt for a SaaS or On-premise aproach, you'll have to create workers to allow to run the CI/CD pipelines.

## How does it work?[​](#how-does-it-work "Direct link to How does it work?")

There are several ways to deploy your own workers, depending in your cloud provider and your requirements.

You can easily create new workers using the cycloid console that will give you instructions on how to do it, using predefined and automated procedures.

![workers](/assets/images/workers-46b80ae68fe851c2b1519e1e73f1dde0.png)

## More details[​](#more-details "Direct link to More details")

For more detailed use cases and information, visit our documentation page on [Workers](/reference/ci-cd-pipelines/concepts/workers/.md) doc pages.

[Go to the Workers documentation](/reference/ci-cd-pipelines/concepts/workers/.md)


---

# Cycloid CLI

The Cycloid CLI is a command-line interface tool designed for streamlined interaction with Cycloid's platform services.

Allowing you to perform the different functionalities of cycloid trough a set of commands

Here at Cycloid, our DevOps team is using it almost every day to perform routine tasks, technical demonstrations for new customers, or even to send events to the Cycloid console.

The Cycloid CLI is one of our Open Source projects. If you want to contribute to it, you can check out the code on our [Github repository](https://github.com/cycloidio/cycloid-cli).

[Go to the CLI documentation](/reference/cli/.md)


---

# InfraMap

InfraMap makes manual diagrams a thing of the past by automatically building a graphical representation of your infrastructure without any input from you.

You'll be able to identify points of error, troubleshoot faster, and ensure everything is up to date with much more ease.

## How does it work?[​](#how-does-it-work "Direct link to How does it work?")

InfraMap reads Terraform state files and creates your infra diagrams in a single click.

Here's a quick demo on how it works.

[YouTube video player](https://www.youtube.com/embed/bLWmgDaEtHQ?si=ITiBug7bE3Dr4dfx)

## Deep dive[​](#deep-dive "Direct link to Deep dive")

For more information don't hesitate to visit our [inframap's github repository](https://github.com/cycloidio/inframap).


---

# Terracognita

TerraCognita is our open-source “reverse” Terraform.

It allows you to generate infra-as-code and/or terraform state files from your current public cloud infrastructure (Azure, AWS, GCP) or VMWare.

If you’re still provisioning your cloud manually, you know it’s time to make the move to reproducible, error-free, and simple IaC.

TerraCognita makes it possible.

## How does it work?[​](#how-does-it-work "Direct link to How does it work?")

It quickly and automatically creates Terraform from all of your manually-provisioned resources, allowing them to be easily replicated and managed by you and your cloud provider.

No more infra drift or time wasted - all you have to do is connect to your cloud and let TerraCognita take care of the rest.

Here's a quick demo of how it works.

[![asciicast](https://asciinema.org/a/330055.svg)](https://asciinema.org/a/330055)

## Deep dive[​](#deep-dive "Direct link to Deep dive")

For more information don't hesitate to visit our [terracognita's github](https://github.com/cycloidio/terracognita).


---

# Terracost

TerraCost automatically gives you insight into the total cost of your deployments - before you actually deploy them.

No more unexpected bills - know exactly how much you’re spending in real time.

## How does it work?[​](#how-does-it-work "Direct link to How does it work?")

TerraCost uses your Terraform plan to automatically output the cost of resources and to show how that cost evolves from one deployment to the next.

It uses a Go library for estimating these costs using ingested cloud vendor prices.

It is intended to be imported and used by programs (APIs or standalone) with access to a MySQL-compatible database and the internet.

## Deep dive[​](#deep-dive "Direct link to Deep dive")

For more information don't hesitate to visit our [terracost's github](https://github.com/cycloidio/terracost).


---

# Feature reference

This documentation section centralize all the technical documentation and specification of Cycloid platform. Use the index on the sidebar to the left to browse each feature or use the integrated search.

## Feature list[​](#feature-list "Direct link to Feature list")

| Name                                                                          | Description                                                                                                                                         |
| ----------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Organizations](/reference/organizations/.md)                                 | Create and manage a cycloid organization                                                                                                            |
| [Projects](/reference/projects/.md)                                           | Main element to use a stack, it contains environments and provides access to automation pipelines, stackforms, InfraView, and more                  |
| [Credentials](/reference/credentials/.md)                                     | Manage sensitive values in your organization                                                                                                        |
| [Stacks](/reference/stacks/.md)                                               | Offer users a service catalog of pre-designed, pre-configured stacks                                                                                |
| [Stack blueprint](/reference/stack-blueprint/.md)                             | Templates allows stack creators to quickly start writing a stacks by selecting a pre-defined Blueprint                                              |
| [Stackforms](/reference/stackforms/.md)                                       | Make dynamic forms to expose configuration to stack users                                                                                           |
| [Config and Catalog Repository](/reference/config-and-catalog-repository/.md) | GitOps components to store stacks and configurations                                                                                                |
| [CI/CD pipelines](/reference/ci-cd-pipelines/.md)                             | Centralize all your deployments in one tool and orchestrate every pipeline with ease                                                                |
| [Cost estimation](/reference/cost-estimation/.md)                             | Cost estimation of any Terraform-defined infrastructure                                                                                             |
| [Events](/reference/events/.md)                                               | Track activity in your organizations                                                                                                                |
| [Asset Inventory](/reference/inventory/.md)                                   | One place to easily view, analyze, and understand all your assets across projects and environments                                                  |
| [Infra Import](/reference/infra-import/.md)                                   | Industrialize manually deployed infra by automatically creating IaC                                                                                 |
| [InfraView](/reference/infraview/.md)                                         | Provides a centralized graphical representation of your infrastructure                                                                              |
| [Infrapolicies](/reference/infrapolicies-policy-as-code/.md)                  | Implementation of Policy as Code (opens new window). The idea is to have fine-grained control over changes across an organization's infrastructures |
| [Cycloid CLI](/reference/cli/.md)                                             | CLI to interact with Cycloid                                                                                                                        |
| [Cloud Cost Management](/reference/cloud-cost-management/.md)                 | An easy way to view, manage and explore your cloud costs                                                                                            |
| [Cloud Carbon Footprint](/reference/cloud-carbon-footprint/.md)               | An easy way to view, manage and explore your cloud footprint                                                                                        |
| [Open Source Software](/reference/oss/.md)                                    | Open Source software made available by Cycloid                                                                                                      |
| [Cycloid API](/api/)                                                          | Cycloid API documentation                                                                                                                           |
| [Dedicated-platform](/reference/dedicated-platform/.md)                       | Documentation to install your own Cycloid platform                                                                                                  |


---

# API

## Introduction[​](#introduction "Direct link to Introduction")

The Cycloid product is written in Golang (Backend) and NodeJS (Frontend). In simple terms, this means that anything you do in the Cycloid web console can also be done or automated using our API.

You can make raw API calls, but it might often be easier to use our [Cycloid CLI](/reference/cli/.md), which is also embedded in our cycloid-toolkit Docker image for pipelines.

## Prerequisites[​](#prerequisites "Direct link to Prerequisites")

To use our API, you need an API key for authentication. Instructions on how to create an API key are explained in the following sections.

## Concepts[​](#concepts "Direct link to Concepts")

### API key[​](#api-key "Direct link to API key")

If you go deeper in workflow automation and want to use Cycloid API to automate the creation of the project, external pipeline triggering, send Events, ... Api Keys are made for you.

Api Keys offers a way to authenticate on Cycloid API using a token with dedicated permissions.

API Keys allow you to create a key with specific permissions for a desired use case.

#### Details[​](#details "Direct link to Details")

Once you are on the details page, you can have a more insightful view about the API Key.

It's also possible to change the owner, name or a description of the API Key.

It consists of the two sections:

1. Api Key name and description:

![API Key name and description fields](/assets/images/api-key-details-section-8a0896380b8b6d3c43636b0eb44a8650.png)

2. Permissions Overview:

![Permissions](/assets/images/permissions-overview-b03586ab62d7c48ab5280934bb1fa6db.png)

#### Create API Key[​](#create-api-key "Direct link to Create API Key")

First, we need to name the API Key and write an optional short description of its purpose.

![API Key name and description fields](/assets/images/api-key-name-and-description-8817bd7fa680066b3588b0a639d067a2.png)

Then, we define the scope for individual actions. These actions can be of various types: creating a project, deleting a credential, reading roles, etc.

These policies can also be narrowed down to specific entities. So that, if you were to have multiple credentials, you could create a role containing policies only for a specific subset of credential. Thus allowing you to have a thinner control on who can do what.

When the API key is created successfully, a modal containing API Key will be displayed.

warning

Be sure to make a copy of the access key below. It’s only displayed upon creation, and you won’t be able to retrieve it later.

![API Key success modal](/assets/images/api-key-success-modal-2cbb1f6ac4fd422ebfa6af0ea3e43dcd.png)

#### Delete API Key[​](#delete-api-key "Direct link to Delete API Key")

The API Key can be deleted in the API Key details view by clicking on the delete button

![Delete API Key](/assets/images/delete-api-key-e625ade531737f7c2928829e00b8511d.png)

or in the list view, where you can use the bulk delete option if you want to delete one or more API Keys.

![Delete API Keys](/assets/images/delete-api-keys-cb0678d754e9e2d01cea3a6a3b8e469e.png)

warning

Deleting API Key will revoke it. Before deleting the API Key, make sure it's not used by script or other users, and that deletion won't break anything.

#### API Keys List[​](#api-keys-list "Direct link to API Keys List")

List view displays all available API Keys that exists inside of the organization.

![List of API Keys](/assets/images/api-keys-list-627a067252bc1d6eace69c132a6a9d92.png)

## Reference[​](#reference "Direct link to Reference")

* See Cycloid [api documentation](/api/).
* See Cycloid [api swagger file](/api/swagger.yaml).


---

# CI/CD pipelines

Cycloid CI/CD enables the creation of immutable pipelines, ensuring that each pipeline job build is based on a defined set of external resources and dependencies. This eliminates issues related to unpredictable changes in resources, providing a stable and reproducible build environment.

Our pipeline engine orchestrate an entire workflow through a visual interface.

You can use it to build an application, create an infrastructure, deploy an application, interact with monitoring tool, and all others steps you could imagine...

Our pipeline engine is based on the open-source [Concourse CI software](https://github.com/concourse/concourse).

![Cycloid Pipeline Sample](/assets/images/cycloid-pipeline-sample-7b0e8505ec3423e81d1db46305d79d5f.png)

## Introduction[​](#introduction "Direct link to Introduction")

A stack contains one or more pipelines. A pipeline describes an **entire workflow**, not only a CI/CD process. This means a pipeline can be triggered by any external components such as infrastructures, Docker registries, Git repositories, object storage, and more (referred to as resources).

In the Cycloid ecosystem, the process of merging stack configurations (as described in the [stack concept documentation](/reference/stacks/concepts/stack-concept.md)) is facilitated through a pipeline that listens to both the stack and configuration repositories within Git. Typically, our helper script `merge-stack-and-config` described later in this section, provided in the **cycloid-toolkit** Docker image, is utilized to accomplish this task.

Additionally, it can interact with these resources, for example, creating a Git commit or pushing a Docker image.

Pipelines are extended by resources and **natively embed credential** management using [Hashicorp's Vault](https://www.vaultproject.io).

This offers a flexible way to describe and orchestrate the lifecycle of an application and infrastructure. Moreover, it provides the possibility to be used for operational automation purposes.

Our current pipeline engine is based on the open-source Concourse CI software. It brings flexibility and **immutability through Docker containers**. Pipelines are configured as code through a **YAML definition**.

The pipeline engine is composed of two components:

* **Scheduler**: In charge of pipelines display and giving instructions to workers.
* **Workers**: The actual pool of servers running jobs and tasks described in a pipeline. More details are provided in the workers section.

![pipeline-archi](/assets/images/pipeline-archi-97977a1638c865516c4a628836a90e09.png)

**Under the hood**

One basic lexicon to understand about pipelines is the difference between what we call a pipeline template and a running pipeline.

* **Pipeline template**: This is the source code of the pipeline, written in YAML and stored in the Git repository of your stack.
* **Running pipeline**: When you create a project using a stack, it reads the pipeline template in Git, injects user input variables into it, and sends it to our pipeline engine (Concourse).

![pipeline-archi-detailed](/assets/images/pipeline-archi-detailed-9e71b4e13b1164a2222998fe9734fbd2.png)

The template of a pipeline is contained in the stack repository. This template is used **only** when you create an environment. This means that if you edit the pipeline using the Dashboard, you are actually editing the running pipeline created from the template, not the template itself.

This also means that updating the template will not update the running pipelines that you have already created. To refresh your running pipeline using the latest version of the template, you can simply click on the refresh pipeline option in the pipeline view. Or edit the configuration with stackforms (in the configuration tab). By saving a new configuration it will also update the pipeline.

Important

It's important to understand the difference between a **pipeline template** and a **running pipeline**.

## Prerequisites[​](#prerequisites "Direct link to Prerequisites")

Before running a pipeline, you need to configure at least one **worker** for your Organization. If no worker is configured, attempting to run a pipeline will result in a "no worker available" error message.

If there is no worker for your current Organization, contact an administrator or connect one to your organization by following the [Connect a worker](/reference/ci-cd-pipelines/concepts/workers/.md#how-to-deploy) section.


---

# Cycloid toolkit

## Overview[​](#overview "Direct link to Overview")

The `cycloid/cycloid-toolkit` Docker image, available at [cycloidio/docker-cycloid-toolkit](https://github.com/cycloidio/docker-cycloid-toolkit/tree/develop), is a comprehensive utility designed to facilitate various DevOps tasks within the Cycloid platform. Its primary purpose is to provide a pre-configured environment with essential tools for CI/CD pipelines, infrastructure management, and automation.

The Docker image includes pre-installed tools such as Terraform, Ansible, Helm, jq, yq, curl, wget, Git, and more. It also comes with helper scripts to streamline the Cycloid stack approach and the usage of tools like Terraform and Ansible.

This is an example of how to run commands in a pipeline using the Cycloid toolkit image:

pipeline.yaml

```
jobs:
- name: job-hello-world
  build_logs_to_retain: 3
  plan:
  - task: hello-world
    config:
        platform: linux
        image_resource:
            type: registry-image
            source: {repository: cycloid/cycloid-toolkit, tag: latest}
        run:
          path: /bin/sh
          args:
          - -ec
          - |
            echo "my commands here"
        params:
          MYENVVAR: "foo"
```

Cycloid helpers scripts:

| Script Name                 | Description                                                                                                                                                                                                                                          |
| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `merge-stack-and-config`    | Helper script based on environment variables to merge Cycloid config directory on top of a Cycloid stack.                                                                                                                                            |
| `ansible-runner`            | Wrapper and helper script on top of the `ansible-playbook` command. It provides features such as automatic run of Ansible Galaxy, loading SSH keys into an agent, and environment variables to configure Ansible and provide variables.              |
| `ansible-runner-inventory`  | Wrapper on top of the `ansible-inventory` command. Its purpose is to help troubleshoot Ansible inventory issues, maintaining all features and automatic inventory load from `ansible-common.sh`.                                                     |
| `extract-terraform-outputs` | This script is primarily used by the `merge-stack-and-config` script. Its purpose is to export all Terraform outputs as both YAML and shell script files, in addition to loading them as environment variables in the current shell execution scope. |
| `aws-ami-cleaner`           | Provides a way to clean old Amazon AMIs. Usually useful when you frequently build new AMIs for your ASG.                                                                                                                                             |
| `aws-ecr-cleaner`           | Provides a way to clean old Docker images from ECR. Usually useful when you frequently build new images for your ECS.                                                                                                                                |
| `vault-approle-login`       | This script uses environment variables for configuration to get a Vault token using AppRole auth. The token is inserted into a Terraform variable file.                                                                                              |

How to use those scripts can be found directly in our public github repository <https://github.com/cycloidio/docker-cycloid-toolkit/tree/develop>

## Running Pre or Post Commands with Toolkit Scripts[​](#running-pre-or-post-commands-with-toolkit-scripts "Direct link to Running Pre or Post Commands with Toolkit Scripts")

When using Cycloid toolkit scripts, you may want to execute pre or post commands before or after invoking your main script. Here’s how to do it:

Regular script call example

pipeline.yaml

```
  - task: run-ansible
    config:
      platform: linux
      image_resource:
        type: registry-image
        source:
          repository: cycloid/cycloid-toolkit
          tag: latest
      run:
        path: /usr/bin/ansible-runner
```

Modified script call with Pre and Post commands

pipeline.yaml

```
  - task: run-ansible
    config:
      platform: linux
      image_resource:
        type: registry-image
        source:
          repository: cycloid/cycloid-toolkit
          tag: latest
      run:
        path: /bin/bash
        args:
        - -ec
        - |
          echo "Here is a PRE command"
          /usr/bin/ansible-runner
          echo "Here is a POST command"
```

Steps to modify:

1. Update the `path` field of your task to specify another command such as `bash` or `sh`.
2. Add the `args` field immediately below the `path` to configure your custom shell script for execution.

This method is commonly utilized with tools like `ansible-runner` to inject a dynamically generated static inventory file or with scripts like `merge-stack-and-config` to apply on-the-fly patches or sed commands to stack code for testing purposes. This approach is applicable to any `task` that utilizes a Docker image with shell capabilities.

## Stack Concept with Merge Stack and Config[​](#stack-concept-with-merge-stack-and-config "Direct link to Stack Concept with Merge Stack and Config")

As described in the Cycloid stack section, one approach to organizing infrastructure as code is called the [stack concept](/reference/stacks/concepts/stack-concept.md). This concept involves splitting generic files from user inputs.

We usually implement this concept in the pipeline, simplified with the `merge-stack-and-config` script in our Cycloid toolkit Docker image.

For Terraform or Ansible, it's best to create a new stack using our [blueprint feature](/reference/stack-blueprint/.md), which already contains pipeline implementation examples.

If you want to use this concept with other technologies, you can learn more about Terraform and Ansible implementations in the [tools-integration section](/reference/ci-cd-pipelines/concepts/tools-integration/.md) to adapt it to your specific needs and technology.


---

# Interface

![Pipeline](/assets/images/pipeline-simple-629229b3dd17d13252f7cb4c47bf9890.png)

As described earlier, a pipeline contains resources (black) and jobs (green). Resources represent external components, such as a Git repository, and jobs represent tasks to execute.

**How to read the pipeline above?**

This pipeline example shows a Git resource listening for new code changes and two jobs interacting with this resource: `test` and `deploy`.

* The `test` job interacts directly with the `Git` resource.
* The `deploy` job depends on the `test` job and interacts only with Git commits that pass the `test` job.

Additionally:

* The resource is linked to the `test` job with a full link ![](/img/job-full-link.png) that's indicates that the job will, indicating the job will automatically trigger if a new Git commit is detected.
* The `deploy` job link is marked with a dot link, ![](/img/job-dot-link.png) meaning it requires a manual trigger.

This choice is made by enabling the `trigger: true/false` property on the job. This is typically used for approval processes, such as requiring human validation between Terraform plan and apply jobs.

To trigger the job, click on it and press the "+" button ![](/img/trigger-job.png)

The logs and details, such as the Git commit used during the execution of the job (called a build), will be displayed.

![Job Details](/assets/images/job-details-7bd5370af70049cfe95a11839edd20f4.png)

tip

See more about pipelines format here :

* <https://concourse-ci.org/pipelines.html>
* <https://concoursetutorial.com/basics/basic-pipeline.html>
* <https://github.com/pivotalservices/concourse-pipeline-samples>


---

# Pipeline

In this section, we will go through basic pipeline components and formats before moving on to more advanced tips.

The current pipeline engine embedded in Cycloid is [Concourse CI](https://concourse-ci.org/).

This engine is based on Docker images, meaning that inside a pipeline, everything runs in a container! This enforces immutability between each CI build and offers flexibility by allowing you to provide your own images.

A pipeline is a definition of [jobs](https://concourse-ci.org/jobs.html) and [resources](https://concourse-ci.org/resources.html) within YAML files.

![Pipeline Components](/assets/images/pipeline-resources-builds-a93a1501ed82fe8e0fdbf20d2c9ae103.png)

## Main components[​](#main-components "Direct link to Main components")

### Jobs[​](#jobs "Direct link to Jobs")

Jobs determine the actions of your pipeline and how resources progress through it. A job consists of a sequence of steps—`get`, `put`, and `task`—to execute the pipeline's workload. These steps define the job's inputs and outputs, and when a job is executed, it creates a **build**.

* **Get/Put**: Defines interaction between a job and resources.
* **Task**: A single unit of work within a job that specifies the command or script to be executed in a containerized environment.
* **Build**: The execution of a job, containing the output of tasks and the version of resources used during the build. Builds are marked with incremental identifiers such as "Build 1," "Build 2," etc.

### Resources[​](#resources "Direct link to Resources")

**Resources** represent external sources or destinations that a pipeline interacts with, such as Git repositories, S3 buckets, or more abstract entities like scheduled or interval triggers via the time resource. The state of a resource is represented by **versions** that can be obtained or created using `put`/`get`.

There are many available resources for various purposes. A non-exhaustive list can be found [here](https://resource-types.concourse-ci.org/).

Resources are Docker images, and you can use community resources by specifying the image address and tag under the `resource_type` section. If no existing resource fits your needs, you can write your own following the [Concourse Official resource guide](https://concourse-ci.org/implementing-resource-types.html).

For example, a [time resource](https://github.com/concourse/time-resource) could trigger a job every day at 12 PM, while a [git resource](https://github.com/concourse/git-resource) could trigger a job based on the commits, tags, or branches of a Git repository. These resources can also be used to perform actions, such as [reporting status on a Git repository](https://github.com/dpb587/github-status-resource) or [notifying a Slack channel](https://github.com/cloudfoundry-community/slack-notification-resource).

### Jobs - Resources Interactions[​](#jobs---resources-interactions "Direct link to Jobs - Resources Interactions")

Jobs interact with resources by getting data from a specific resource version (`get`) or sending data to create a new version (`put`).

For example, with a Git resource:

* A `get` operation would clone a repository to obtain the source code for a specific commit.
* A `put` operation would commit and push changes to create a new commit.

For an AWS S3 bucket:

* A `get` operation would download an object.
* A `put` operation would upload an object to the bucket.

Below is an example of a job interacting with a Git resource to retrieve source code and a deploy job using an AWS S3 resource to deploy files:

![Pipeline example](/assets/images/pipeline-resources-builds-detailed-cd450d065895244e71ab5baba8207e1c.png)

## Pipeline File Format[​](#pipeline-file-format "Direct link to Pipeline File Format")

info

This section is concise by design, as it is more effective to refer to Concourse's own documentation. Cycloid is built on Concourse, and [the concept of pipelines](https://concourse-ci.org/pipelines.html) is thoroughly defined there.

Concourse CI pipelines are defined in YAML format.

![Pipeline format](/assets/images/pipeline-format-render-c5749491ff3e918e86ce1c92f492dc0b.png)

pipeline.yaml

```
---
resource_types:
- name: my-custom-notification-resource
  type: registry-image
  source:
    repository: my-dockerhub-user/my-custom-resource
    tag: latest

resources:
- name: source-code
  type: git
  source:
    uri: https://github.com/example/repo.git
    branch: main

- name: custom-resource-notify
  type: my-custom-notification-resource
  source:
    some: configuration

jobs:
- name: build
  plan:
  - get: source-code
    trigger: true
  - task: build-task
    config:
      platform: linux
      image_resource:
        type: registry-image
        source:
          repository: busybox
      inputs:
      - name: source-code
      run:
        path: sh
        args:
        - -exc
        - |
          cd source-code
          echo "Building the project..."
  - put: custom-resource-notify
```

**Explanation:**

1. **Resource Types**:

   * `my-custom-notification-resource`: A custom resource type defined using a Docker image from Docker Hub. This resource could be used to send notification messages to an internal chat system.

2. **Resources**:

   * `source-code`: A Git resource pointing to a GitHub repository.
   * `custom-resource-notify`: An instance of the custom resource type with specific configuration.

3. **Jobs**:

   * `build`: A job that includes:

     <!-- -->

     * A `get` step to fetch the `source-code`, **triggering** the job on new commits due to the `trigger: true` parameter.
     * `inputs`: Specifies directories available to the task's container, providing necessary files and data.
     * A `task` step named `build-task` that runs a build script inside a container based on the `busybox` image.
     * A `put` step to use the `custom-resource-notify` to trigger a notification at the end of the job.

Note

In addition to `inputs`, a task can contain an `outputs` section, which specifies directories available after the task's execution. These outputs typically represent artifacts or results generated by the task that need to be passed to subsequent steps in the pipeline.

This example fetches the latest code from a specified Git repository, runs a simple build task, and then uses a custom resource to trigger notifications on an internal chat system.

## Pipeline Variables[​](#pipeline-variables "Direct link to Pipeline Variables")

Variables in pipelines are useful for managing configuration settings, secrets, and other dynamic values. These variables are typically provided either by [stackforms](/reference/stackforms/.md) or through the `variable.sample.yaml` file in your stack definition.

A variable in a Concourse pipeline is represented by `((variable_name))`.

**Example:**

variable.sample.yaml

```
git_repo: https://github.com/example/repo.git
git_branch: main
```

Note

These variables can also be provided by stackforms, using `git_repo` and `git_branch` as widget keys.

**Pipeline Template:**

pipeline.yaml

```
resources:
  - name: source-code
    type: git
    source:
      uri: ((git_repo))
      branch: ((git_branch))

jobs:
  - name: build
    plan:
      - get: source-code
        trigger: true
...
```

### Variable Lookup[​](#variable-lookup "Direct link to Variable Lookup")

In some specific cases, it's crucial to understand how Concourse handles variable lookup.

The behavior is described in detail in the [Concourse credentials documentation](https://concourse-ci.org/creds.html) and [credential lookup rules](https://concourse-ci.org/vault-credential-manager.html#vault-credential-lookup-rules).

There is no difference between regular variables and Cycloid credential variables in a pipeline. Concourse will evaluate and render all the variables provided during pipeline creation.

For each variable not provided, Concourse will assume they are Vault variables.

These variables remain in the `((variable_name))` format and are rendered using Vault only during the runtime of the job.

#### Vault Variable Specification[​](#vault-variable-specification "Direct link to Vault Variable Specification")

When resolving a parameter like `((foo_param))`, Concourse checks the following paths in order:

1. `PIPELINE_NAME/foo_param`
2. `foo_param`

This allows you to define or override credentials for a specific pipeline scope. You can specify the field to fetch using a `.` syntax, e.g., `((foo.bar))`. This will look into your credentials for the path `foo` containing the field name `bar`.

**Specific Field Name:** Vault credentials are key-value pairs. If you indicate only a path like `((foo))`, Concourse defaults to the `value` field, resolving it as `foo.value`.

## Job dependencies and data sharing[​](#job-dependencies-and-data-sharing "Direct link to Job dependencies and data sharing")

### Dependencies[​](#dependencies "Direct link to Dependencies")

Dependencies between jobs in Concourse are managed through resources using the [`passed`](https://concourse-ci.org/get-step.html#schema.get.passed) keyword.

> When specified, only the versions of the resource that made it through the given list of jobs (AND-ed together) will be considered when triggering and fetching.

Let's take the example of running **job deploy** after **job test**:

* Rendering
* Code

![img](/assets/images/pipeline-job-dependencies-bc12f23ca575cfe8b0b7582abf25c96c.png)

pipeline.yaml

```
resources:
- name: source-code
  type: git
  source:
    uri: https://github.com/example/repo.git
    branch: main

jobs:
  - name: test
    plan:
      - get: source-code
        trigger: true

  - name: deploy
    plan:
      - get: source-code
        trigger: true
        passed: [test]
```

This way, the deploy job will only run on Git commits that have successfully passed through the test job.

### Data sharing[​](#data-sharing "Direct link to Data sharing")

In Concourse CI, you can share "local" data only between tasks and resources within the same job. However, sharing data across two jobs requires consideration of the distributed nature of job execution on a pool of worker instances. This means job `A` might run on a different worker than job `B`.

To share data between jobs, you need to use resources. The choice of resource depends on the type of data and could include S3 buckets, Docker registries, Git, key/value stores, etc.

Here is an example using S3 object storage.

* Rendering
* Code

![img](/assets/images/pipeline-shared-data-d5596b7956b02313ee98b2a4bcd698d9.png)

pipeline.yaml

```
resources:
- name: s3-bucket
  type: s3
  source:
    bucket: my-s3-bucket
    region_name: eu-west-1
    access_key_id: ((s3_access_key_id))
    secret_access_key: ((s3_secret_access_key))
    versioned_file: path/to/versioned/file

jobs:
- name: job-A
  plan:
  - task: task-in-A
    config:
      platform: linux
      image_resource:
        type: registry-image
        source:
          repository: busybox
      outputs:
      - name: build-output
      run:
        path: sh
        args:
        - -exc
        - |
          echo "Building in Job A"
          echo "content from job A" > build-output/output.txt
  - put: s3-bucket
    params:
      file: build-output/output.txt

- name: job-B
  plan:
  - get: s3-bucket
    trigger: true
    passed: [job-A]
  - task: task-in-B
    config:
      platform: linux
      image_resource:
        type: registry-image
        source:
          repository: busybox
      inputs:
      - name: s3-bucket
      run:
        path: sh
        args:
        - -exc
        - |
          echo "Processing in Job B"
          cat s3-bucket/output.txt
```

**Job A**:

* `job-A`: The first job that performs a task.
* It creates an output file (`output.txt`) in the `build-output` directory.
* It then uploads this file to the S3 bucket using the `put` step.

**Job B**:

* `job-B`: The second job that depends on the completion of `job-A`.
* The `get` step for `s3-bucket` specifies `passed: [job-A]` to ensure it only runs after `job-A` successfully completes and uploads the file.
* It retrieves the file from the S3 bucket and processes it.

## Stack concept in pipelines[​](#stack-concept-in-pipelines "Direct link to Stack concept in pipelines")

As described in the [stack concept](/reference/stacks/concepts/stack-concept.md), a stack splits the infrastructure as code into two parts: the generic stack and the user configuration, stored in different Git repositories (or branches).

To run tools such as Terraform, Ansible, and others, these two parts need to be merged at some point.

An easy way to achieve this is by using a helper script called `merge-stack-and-config`, provided in our **cycloid-toolkit** Docker image. More details will be provided in the dedicated section, but here is a small example of how it can be done in the pipeline:

* Rendering
* Code

![img](/assets/images/pipeline-stack-config-c767d3d6a74ea0392dc9d1b4b6779adb.png)

pipeline.yaml

```
# YAML anchors
shared:
  - &merge-stack-and-config
    platform: linux
    image_resource:
      type: registry-image
      source:
        repository: cycloid/cycloid-toolkit
        tag: latest
    run:
      path: /usr/bin/merge-stack-and-config
    outputs:
    - name: merged-stack
      path: "merged-stack"

resources:
  - name: git_config
    type: git
    source:
      branch: config
      uri: 'https://github.com/example/repo.git'
  - name: git_stack
    type: git
    source:
      branch: stacks
      uri: 'https://github.com/example/repo.git'

jobs:
  - name: test
    plan:
      - get: git_stack
        trigger: true
      - get: git_config
        trigger: true
      - task: merge-stack-and-config
        config:
          <<: *merge-stack-and-config
          inputs:
          - name: git_config
            path: "config"
          - name: git_stack
            path: "stack"
        params:
          CONFIG_PATH: myconfig/path
          STACK_PATH: stack-path
```

In addition to using our helper `merge-stack-and-config` script, we are using a native YAML feature called aliases/anchors. This feature, described in the [YAML specification](https://yaml.org/spec/1.2-old/spec.html#id2786196), allows defining a YAML section and referring to it as a block of code. This is really useful when writing a pipeline to factorize some parts of the code. For example, you might want to call the `merge-stack-and-config` task in several jobs.

The merge of the stack and the config is implemented through a task that can be used in any job. The task uses our public `cycloid/cycloid-toolkit` Docker image and takes as inputs both Git repositories (the stack and the config). Then, we simply need to provide the directories to sync inside those Git repositories using the `CONFIG_PATH` and `STACK_PATH` parameters.

## Using Images from a Private Docker Registry[​](#using-images-from-a-private-docker-registry "Direct link to Using Images from a Private Docker Registry")

To use a Docker image from a private registry, you need to add the `username` and `password` source parameters for every `resource_type` or `task`.

We assume the username and password of the registry are stored in a Cycloid credential of type `basic_auth`.

Here are some examples:

* resource\_types
* task

pipeline.yaml

```
resource_types:

  - name: myresource
    type: registry-image
    source:
      repository: foo/mydockerimage
      tag: 'latest'
      username: ((basic_auth_credential_name.username))
      password: ((basic_auth_credential_name.password))
```

pipeline.yaml

```
jobs:
...

  - task: mytask
    config:
      platform: linux
      image_resource:
        type: registry-image
        source:
          repository: foo/mydockerimage
          tag: latest
          username: ((basic_auth_credential_name.username))
          password: ((basic_auth_credential_name.password))
      run:
        path: /bin/sh
```

## Using a docker registry mirror[​](#using-a-docker-registry-mirror "Direct link to Using a docker registry mirror")

You will need to add the `registry_mirror` source parameter for every `resource` or `task` of type `registry-image` or `registry-mirror` like the following:

* resource\_types
* task

pipeline.yaml

```
resource_types:
...
  # registry-image type
  - name: myresource
    type: registry-image
    source:
      repository: foo/mydockerimage
      tag: 'latest'
      registry_mirror:
        # registry-image only support TLS secured registries
        host: <your-registry-mirror-fqdn>:<your-registry-mirror-port>
...
  - name: myresource
    type: registry-image
    source:
      repository: foo/mydockerimage
      tag: 'latest'
      registry_mirror: 'https://<your-registry-mirror-fqdn>:<your-registry-mirror-port>'
      # for HTTP add the following
      # insecure_registries: ['<your-registry-mirror-fqdn>:<your-registry-mirror-port>']
```

pipeline.yaml

```
jobs:
...

  # registry-image type
  - task: mytask
    config:
      platform: linux
      image_resource:
        type: registry-image
        source:
          repository: cycloid/cycloid-toolkit
          tag: latest
          registry_mirror:
            # registry-image only support TLS secured registries
            host: <your-registry-mirror-fqdn>:<your-registry-mirror-port>
      run:
        path: /bin/sh
...
  - task: mytask
    config:
      platform: linux
      image_resource:
        type: registry-image
        source:
          repository: cycloid/cycloid-toolkit
          tag: latest
          registry_mirror: 'https://<your-registry-mirror-fqdn>:<your-registry-mirror-port>'
          # for HTTP add the following
          # insecure_registries: ['<your-registry-mirror-fqdn>:<your-registry-mirror-port>']
      run:
        path: /bin/sh
```

## Additionnals useful syntax[​](#additionnals-useful-syntax "Direct link to Additionnals useful syntax")

### `groups` / views[​](#groups--views "Direct link to groups--views")

The `groups` option allows you to organize jobs into named groups for better visualization and management in the UI. This feature is especially useful in large pipeline workflows. A common use case is to separate the infrastructure part from the application build and deployment part, creating specific views for different personas such as Dev, DevOps, etc. This organization enhances clarity and efficiency in managing complex pipelines.

* Rendering
* Code

![img](/assets/images/pipeline-groups-5903de680bcead24da16996ec0d79a17.gif)

pipeline.yaml

```
groups:
- name: all
  jobs: [build-job, unit-test-job, integration-test-job]

- name: build-group
  jobs: [build-job]

- name: test-group
  jobs: [unit-test-job, integration-test-job]

resources:
- name: code
  type: git
  source:
    uri: https://github.com/example/repo.git
    branch: main

jobs:
- name: build-job
  plan:
  - get: code
    trigger: true

- name: unit-test-job
  plan:
  - get: code
    trigger: true
    passed: [build-job]

- name: integration-test-job
  plan:
  - get: code
    trigger: true
    passed: [build-job]
```

The `groups` section defines three groups: `all`, `build-group`, and `test-group`.

* `all` includes all jobs to provide a global overview of the pipeline workflow and dependencies.
* `build-group` and `test-group` display only specific jobs for focused views.

This feature enhances clarity and efficiency in managing complex pipelines by creating specific views for different personas such as Dev and DevOps.

For more details, refer to the [Concourse CI documentation on groups](https://concourse-ci.org/pipelines.html#schema.pipeline.groups).

### `caches`[​](#caches "Direct link to caches")

The `caches` option allows you to define directories that should be cached across task executions on the same worker, improving performance by preserving intermediate files and dependencies.

This can be particularly useful when building applications that require downloading public libraries, such as Node.js. By caching these dependencies, you can avoid redundant downloads and significantly speed up the build process.

Example

pipeline.yaml

```
jobs:
- name: job-with-cache
  plan:
    - config:
        platform: linux
        image_resource:
            type: registry-image
            source:
                repository: busybox
        run:
            path: sh
            args:
            - '-exc'
            - |-
                if [ -f "my-cache/cache.txt" ]; then
                    echo "Cache exists"
                else
                    echo "Cache does not exist, creating cache directory"
                    echo "Cache content" > my-cache/cache.txt
                fi
                cat my-cache/cache.txt
        caches:
        - path: my-cache
      task: cached-task
```

* The `caches` section specifies a directory (`my-cache`) that should be cached.
* On subsequent executions on the same worker, the contents of `my-cache` will be preserved, avoiding redundant work.

This feature is particularly useful for tasks that involve expensive setup steps or require intermediate files that don't change often. For more details, refer to the [Concourse CI documentation on caches](https://concourse-ci.org/tasks.html#schema.task-config.caches).

### `on_success`, `on_failure` job hooks[​](#on_success-on_failure-job-hooks "Direct link to on_success-on_failure-job-hooks")

The `on_success` and `on_failure` steps allow you to define actions that should be executed based on the success or failure of a preceding step. The `do` step is used to group multiple steps to be executed sequentially within the job.

* **`on_success`**: Executes a step only if the preceding step succeeds.
* **`on_failure`**: Executes a step only if the preceding step fails.
* **`do`**: Groups a sequence of steps to be executed in order, useful for running multiple steps under a conditional.

Here's an example pipeline that uses `do`, `on_success`, and `on_failure` to send notifications upon the success or failure of a job:

* on-success
* on-failure
* Code

![img](/assets/images/pipeline-on-success-a540db1d2d574e37b14b61ab74d540de.png)

![img](/assets/images/pipeline-on-failure-e658d63648ffc13613e7c669f6214f44.png)

pipeline.yaml

```
resources:
  - name: email-notifier
    type: dummy

resource_types:
  - name: dummy
    type: registry-image
    source:
      repository: ktrysmt/concourse-dummy-resource

jobs:
  - name: build-job
    plan:
      - do:
          - config:
              platform: linux
              image_resource:
                type: registry-image
                source:
                  repository: busybox
              run:
                path: sh
                args:
                  - '-c'
                  - |
                    echo "Building..."
                    # Simulate a build process
                    exit 0  # Simulate a failure for demonstration
            task: build
          - config:
              platform: linux
              image_resource:
                type: registry-image
                source:
                  repository: busybox
              run:
                path: sh
                args:
                  - '-c'
                  - |
                    echo "Building..."
                    # Simulate a build process
                    exit 1  # Simulate a failure for demonstration
            task: build2
        on_failure:
          params:
            body: The build-job has failed.
            subject: Build Failed
          put: email-notifier
        on_success:
          params:
            body: The build-job has succeeded.
            subject: Build Succeeded
          put: email-notifier
```

**Resources**:

* `email-notifier`: A fake email resource.

**Job**:

* `build-job`: A job that runs a build task.

  <!-- -->

  * The `do` step groups the `task`, `on_failure`, and `on_success` steps together, ensuring they are executed in sequence.
  * The `task` step simulates a build process. The `exit 1` command is used to simulate a failure for demonstration purposes.

**Notification Steps**:

* `on_failure`: Sends an "email" notification if the `task` step fails.
* `on_success`: Sends an "email" notification if the `task` step succeeds.

For more details, refer to the [`do` step](https://concourse-ci.org/do-step.html) and [`on_(success|failure|error|abord)`](https://concourse-ci.org/jobs.html#schema.job.on_success). For some usecases, in addition you could have a look to the [`try` step](https://concourse-ci.org/try-step.html).

### `load_var` load a variable from a file[​](#load_var-load-a-variable-from-a-file "Direct link to load_var-load-a-variable-from-a-file")

The `load_var` step is used to load a variable from a file. This step is useful for dynamically setting pipeline variables from the output of previous steps, which can then be used in subsequent steps within the job.

* Screenshot
* Code

![img](/assets/images/pipeline-load-var-472cebdcc410b72d9c8a68eef9483858.png)

pipeline.yaml

```
jobs:
- name: example-job
  plan:
  - task: generate-var-file
    config:
      platform: linux
      image_resource:
        type: registry-image
        source:
          repository: busybox
      outputs:
      - name: var-output
      run:
        path: sh
        args:
        - -xc
        - |
          echo "Hello, World!" > var-output/var-file

  - load_var: dynamic_var
    file: var-output/var-file

  - task: use-loaded-var
    config:
      platform: linux
      image_resource:
        type: registry-image
        source:
          repository: busybox
      run:
        path: sh
        args:
        - -xc
        - |
          echo "The loaded variable is: ${myvar}"
          echo $myvar
      params:
        myvar: ((.:dynamic_var))
```

**Steps**:

* `task: generate-var-file`: A task that generates a file containing the value of a variable.
  <!-- -->
  * The file `var-output/var-file` is created with the content `Hello, World!`.
* `load_var: dynamic_var`: Loads the `dynamic_var` variable from the specified file (`var-output/var-file`).
* `task: use-loaded-var`: A task that uses the loaded variable `dynamic_var` as a parameter `params`.
  <!-- -->
  * It prints the value of the loaded variable to demonstrate that it has been successfully loaded.

For more details, refer to the [`load_var` step](https://concourse-ci.org/load-var-step.html).

### `serial_group` to Control Job Execution[​](#serial_group-to-control-job-execution "Direct link to serial_group-to-control-job-execution")

The `serial_group` attribute is used to group jobs that should not run simultaneously. By assigning the same `serial_group` name to multiple jobs, only one job from the group is executed at any given time. This can help prevent conflicts and manage resources more effectively. It is particularly useful when using technologies such as Terraform for `plan` and `apply` actions, where concurrent executions could lead to conflicts or inconsistent states.

Example

pipeline.yaml

```
jobs:
  - name: job-1
    serial_groups:
      - example-group
    plan:
      - config:
          platform: linux
          image_resource:
            name: ''
            type: registry-image
            source:
              repository: busybox
          run:
            path: sh
            args:
              - '-c'
              - echo "Running task in job-1"
        task: task-in-job-1

  - name: job-2
    serial_groups:
      - example-group
    plan:
      - config:
          platform: linux
          image_resource:
            name: ''
            type: registry-image
            source:
              repository: busybox
          run:
            path: sh
            args:
              - '-c'
              - echo "Running task in job-2"
        task: task-in-job-2
```

* `job-1` and `job-2` are defined with a `serial_groups` attribute set to `example-group`.
* This ensures that `job-1` and `job-2` will not run concurrently; one job will wait for the other to finish before starting.

For more details, refer to the [`serial_group`](https://concourse-ci.org/jobs.html#schema.job.serial_groups) documentation.

To limit the number of parallel executions of a single job, you can also read about [`serial`](https://concourse-ci.org/jobs.html#schema.job.serial) and [`max_in_flight`](https://concourse-ci.org/jobs.html#schema.job.max_in_flight).

## Summary[​](#summary "Direct link to Summary")

Concourse CI's containerized approach for jobs and resources allows for seamless connectivity and execution of various tasks within a pipeline. By using custom Docker images or resources, you can run any language or software and interact with external services through APIs. This flexibility enables you to customize the pipeline to meet the specific needs of your applications and infrastructure.


---

# Pipelines Overview

![Overview](/assets/images/pipelines-overview-6a4719a3f6be7deba91501423d9ec90f.png)

This page gives an overview of all the pipelines that belong to your organization.

By clicking on the pipeline name, you will be automatically redirected to the pipeline details view, showing also the resources.

Using this overview, you are able to quickly know the status of your pipeline with the color code, but also checking how long this status hasn't changed.

## How the status is defined ?[​](#how-the-status-is-defined- "Direct link to How the status is defined ?")

To know the status of a pipeline, we are checking if a job has a different status than "success".

The order to determine this status is:

`Build Running > Paused > Failed > Errored > Aborted > Succeeded`

`Pending` status is displayed only if there is no other build status and every other builds are still in pending status.

## How is the order determined in the pipeline grid[​](#how-is-the-order-determined-in-the-pipeline-grid "Direct link to How is the order determined in the pipeline grid")

![Pipeline Grid](data:image/png;base64,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)

The pipeline grid is computing the rank and dependencies on your pipelines jobs.

For example, on the image above, it represents a `Terraform Runner` pipeline. There are 3 jobs:

1. terraform-plan
2. terraform-apply
3. terraform-destroy

The `terraform-destroy` job is defined in a specific group, but if we take a global overview of the pipeline, it has the same dependency than the `terraform-plan`: it needs the Git repository containing the Terraform code.

The job `terraform-apply` depends on the job `terraform-plan`. As it has a dependency on a rank 1, it will be placed on a rank 2.

Therefore, we have 2 different ranks:

1. `terraform-plan` + `terraform-destroy`
2. `terraform-apply`

As you can see, with those ranks, we can create a grid that will mimic the look of your pipelines, from the left to the right.

To know quickly which job is failing, you can put your mouse over, it will show a tooltip with the job name.

Clicking on it will redirect you automatically to the last build of this job.


---

# Tools integration

This section provides comprehensive information and examples on integrating various common technologies into pipelines.

Pipelines offer flexibility, supporting a diverse tools and technologies, enabling automation and optimization of workflows. Whether leveraging Terraform for infrastructure as code, Ansible for configuration management, or other tools, pipelines facilitate seamless integration and efficient operation within your environment.

Following pages also contain best practices and examples for technologies like Terraform and Ansible, focusing on how to provide **user inputs** or **Cycloid credentials** to specific technologies through the pipeline.


---

# Ansible

Integrating Ansible into a Cycloid pipeline is facilitated by the `ansible-runner` script available in the [`cycloid/cycloid-toolkit`](/reference/ci-cd-pipelines/concepts/cycloid-toolkit.md) Docker image.

`ansible-runner` acts as a wrapper for the `ansible-playbook` command, offering configuration via environment variables to streamline Ansible's integration into a pipeline and provide additional functionalities.

Here’s a brief example demonstrating Ansible integration in a pipeline, following the [stack concept](/reference/stacks/concepts/stack-concept.md):

* Rendering
* Code

![img](/assets/images/pipeline-ansible-run-829617b7a761691b32efa63d63df1052.png)

pipeline.yaml

```
# YAML anchors
shared:
  - &merge-stack-and-config
    platform: linux
    image_resource:
      type: registry-image
      source:
        repository: cycloid/cycloid-toolkit
        tag: "latest"
    run:
      path: /usr/bin/merge-stack-and-config
    outputs:
    - name: merged-stack
      path: "merged-stack"

  - &run-ansible-from-bastion
    config:
      platform: linux
      image_resource:
        type: registry-image
        source:
          repository: cycloid/cycloid-toolkit
          tag: "latest"
      run:
        path: /usr/bin/ansible-runner
      caches:
        - path: ansible-playbook/roles
      inputs:
      - name: merged-stack
        path: ansible-playbook


jobs:
- name: run-ansible
  serial: true
  build_logs_to_retain: 10
  plan:
    - do:
      - get: git_stack
        params: {depth: 1}
        trigger: true
      - get: git_config
        params: {depth: 1}
        trigger: true

      - task: merge-stack-and-config
        config:
          <<: *merge-stack-and-config
          inputs:
          - name: git_config
            path: "config"
          - name: git_stack
            path: "stack"
        params:
          CONFIG_PATH: ($ .project $)/ansible  # This value depend of the stack configuration in .cycloid.yaml file
          STACK_PATH: ($ .stack_path $)/ansible

      - task: run-ansible
        <<: *run-ansible-from-bastion
        params:
          SSH_JUMP_URL: 10.0.0.42
          SSH_PRIVATE_KEY: ((my_cred.ssh_key))
          ANSIBLE_PLAYBOOK_NAME: main.yml
          ANSIBLE_EXTRA_VARS:
            org: ($ .org $)
            project: ($ .project $)
            env: ($ .env $)
```

This example demonstrates how to run an Ansible playbook using `ansible-runner` through a bastion server (`SSH_JUMP_URL`) using a private SSH key sourced from a Cycloid credential.

The `params` section contains environment variables passed to the `ansible-runner` script, typically used for:

* Cycloid [Ansible-runner script environment variables](https://github.com/cycloidio/docker-cycloid-toolkit/tree/develop?tab=readme-ov-file#ansible-runner).
* Standard [Ansible environment variables](https://docs.ansible.com/ansible/latest/reference_appendices/config.html).

## Differents usage of Ansible inventories[​](#differents-usage-of-ansible-inventories "Direct link to Differents usage of Ansible inventories")

If you are familiar with Ansible, you likely know that there are primarily two ways of providing host inventories to Ansible:

* [Static Inventory](https://docs.ansible.com/ansible/latest/inventory_guide/intro_inventory.html): A static list of hosts provided in either `ini` or `yaml` format.
* [Dynamic Inventory](https://docs.ansible.com/ansible/latest/user_guide/intro_dynamic_inventory.html): A script or executable that generates a dynamic list of hosts. For example, major cloud providers offer dynamic inventories based on API calls, allowing retrieval of instance IPs based on cloud provider tags.

### Dynamic inventory[​](#dynamic-inventory "Direct link to Dynamic inventory")

Cycloid's Ansible runner automatically detects and configures dynamic inventories based on cloud provider credential environment variables.

The script currently supports detection for the following dynamic inventories:

* [Amazon EC2 inventory](https://github.com/ansible-collections/amazon.aws)
* [GCP inventory](https://github.com/ansible-collections/google.cloud)
* [Azure inventory](https://github.com/ansible-collections/azure) with Ansible >= 2.8

To use dynamic inventories from cloud providers, the first step is to provide the selected credential to `ansible-runner` in the pipeline:

* Amazon Web Services
* Azure
* Google Cloud Platform

Stackforms [credential widget](/reference/stackforms/reference/widgets/cy_cred.md) definition:

.forms.yaml

```
...
      vars:
        - name: "Cloud provider access"
          widget: cy_cred
          key: cloud_provider_access
          type: "string"
          widget_config:
            display_keys: false
            cred_types: ["aws"]
```

Pipeline ansible runner params:

pipeline.yaml

```
jobs:
- name: run-ansible
...

      - task: run-ansible
        <<: *run-ansible-from-bastion
        params:
          SSH_JUMP_URL: 10.0.0.42
          SSH_PRIVATE_KEY: ((my_cred.ssh_key))
          CY_AWS_CRED: ((cloud_provider_access))
          ANSIBLE_PLAYBOOK_NAME: main.yml
          ANSIBLE_EXTRA_VARS:
            org: ($ .org $)
            project: ($ .project $)
            env: ($ .env $)
```

Stackforms [credential widget](/reference/stackforms/reference/widgets/cy_cred.md) definition:

.forms.yaml

```
...
      vars:
        - name: "Cloud provider access"
          widget: cy_cred
          key: cloud_provider_access
          type: "string"
          widget_config:
            display_keys: false
            cred_types: ["azure"]
```

Pipeline ansible runner params:

pipeline.yaml

```
jobs:
- name: run-ansible
...

      - task: run-ansible
        <<: *run-ansible-from-bastion
        params:
          SSH_JUMP_URL: 10.0.0.42
          SSH_PRIVATE_KEY: ((my_cred.ssh_key))
          CY_AZURE_CRED: ((cloud_provider_access))
          ANSIBLE_PLAYBOOK_NAME: main.yml
          ANSIBLE_EXTRA_VARS:
            org: ($ .org $)
            project: ($ .project $)
            env: ($ .env $)
```

Stackforms [credential widget](/reference/stackforms/reference/widgets/cy_cred.md) definition:

.forms.yaml

```
...
      vars:
        - name: "Cloud provider access"
          widget: cy_cred
          key: cloud_provider_access
          type: "string"
          widget_config:
            display_keys: false
            cred_types: ["gcp"]
```

Pipeline ansible runner params:

pipeline.yaml

```
jobs:
- name: run-ansible
...

      - task: run-ansible
        <<: *run-ansible-from-bastion
        params:
          SSH_JUMP_URL: 10.0.0.42
          SSH_PRIVATE_KEY: ((my_cred.ssh_key))
          CY_GCP_CRED: ((cloud_provider_access))
          ANSIBLE_PLAYBOOK_NAME: main.yml
          ANSIBLE_EXTRA_VARS:
            org: ($ .org $)
            project: ($ .project $)
            env: ($ .env $)
```

From this point, your playbook should be executed by Ansible using the specified cloud provider's dynamic inventory. Ensure that the Ansible `hosts` specified in your playbook match the host groups provided by the dynamic inventory. Refer to the specific dynamic inventory documentation to understand how groups are defined based on cloud provider regions, instance tags, labels, and so forth.

It's important to configure your playbook to target specific instances using these groups, leveraging Ansible's [exclude and include groups](https://docs.ansible.com/ansible/latest/user_guide/intro_patterns.html).

Here's a concrete example using AWS dynamic inventory, assuming instances are tagged with **env=demo** and **project=owl** tags:

From [Ansible dynamic inventory AWS](https://docs.ansible.com/ansible/latest/collections/amazon/aws/aws_ec2_inventory.html) documentation and the default configuration provided by **ansible-runner**, all instance tags are exposed as Ansible groups (`tag_<tag name>_<tag value>`).

Let's use the defined env and project ansible variable from `ANSIBLE_EXTRA_VARS` to compose our hosts filter:

ansible/main.yml

```
- hosts: tag_project_{{ project }}:&tag_env_{{ env }}:!tag_role_frontend
...
```

From this example Ansible will run the playbook on instances matching the tag `project=owl` and (`:&`) `env=demo` tags but exclude (`:!`) those with the tag `tag_role=frontend`.

How to use public IP address

If your servers are located in a private network, `ansible-runner` defaults to using the [Bastion host](https://en.wikipedia.org/wiki/Bastion_host) approach, which means it will use the **private IP addresses** to connect to instances.

If you do not use a bastion server and need to connect using **public IP addresses**, you can add the following `params`:

* For Amazon EC2: `AWS_EC2_COMPOSE_ANSIBLE_HOST=public_ip_address`
* For Azure: `AZURE_USE_PRIVATE_IP=False`
* For GCP: `GCP_USE_PRIVATE_IP=False`

These parameters configure `ansible-runner` to use public IP addresses instead of private IP addresses when connecting to instances in the respective cloud providers. Adjust these settings based on your specific infrastructure setup and requirements.

You can see more configuration options for the `ansible-runner` script [here](https://github.com/cycloidio/docker-cycloid-toolkit/blob/master/README.md#ansible-runner).

Missing Dynamic inventory ?

More dynamic inventories will be added to the `ansible-runner` in the future, but if you need one that is not yet supported, you can:

* Search for existing inventory [plugins](https://docs.ansible.com/ansible/latest/plugins/inventory.html) and [scripts](https://docs.ansible.com/ansible/latest/user_guide/intro_dynamic_inventory.html)
* Develop your [own dynamic inventory](https://docs.ansible.com/ansible/latest/dev_guide/developing_inventory.html)

Then:

* Add it by extending our `cycloid/cycloid-toolkit` docker image
* Or add it as a pre command to [ansible-run task](/reference/ci-cd-pipelines/concepts/cycloid-toolkit.md#running-pre-or-post-commands-with-toolkit-scripts)

### Basic inventory file[​](#basic-inventory-file "Direct link to Basic inventory file")

You can create your inventory file in one of many formats, such as INI or YAML, depending on the inventory plugins you use. The regular usage is well described in the [Ansible documentation](https://docs.ansible.com/ansible/latest/inventory_guide/intro_inventory.html#inventory-basics-formats-hosts-and-groups).

To specify an inventory file in Ansible, there are two recommended ways:

* **Solution 1:** Use the native `ANSIBLE_INVENTORY=inventory_file` environment variable.
* **Solution 2:** Pass `-i inventory_file` as a parameter through `ANSIBLE_EXTRA_ARGS` to our `ansible-runner` helper script.

This section will focus on demonstrating how to integrate a basic inventory file in a pipeline and discuss three methods of achieving this.

#### 1 - Adding it to your Git repository[​](#1---adding-it-to-your-git-repository "Direct link to 1 - Adding it to your Git repository")

This is one of the easiest methods but also quite static. It involves creating a basic Ansible inventory file and committing it to either your stack or config Git repository.

First, place the inventory file in Git. The location of the inventory file is linked to the configuration of the **merge-stack-and-config** task.

```
      - task: merge-stack-and-config
      ...
        params:
          CONFIG_PATH: ($ .project $)/ansible  # This value depends on the stack configuration in .cycloid.yaml file
          STACK_PATH: ($ .stack_path $)/ansible
```

Make sure to commit the inventory file in one of the directories specified by `CONFIG_PATH` or `STACK_PATH`, depending on whether you are using the Stack or Config Git repository.

Next, add the `ANSIBLE_INVENTORY` environment variable to the `run-ansible` task params:

pipeline.yaml

```
      - task: run-ansible
        <<: *run-ansible-from-bastion
        params:
          ANSIBLE_INVENTORY: inventory_file      # Relative path referring to **ANSIBLE_PLAYBOOK_PATH**
          ...
```

#### 2 - Generate a file on-the-fly[​](#2---generate-a-file-on-the-fly "Direct link to 2 - Generate a file on-the-fly")

Alternatively, you can generate the inventory file dynamically within the pipeline as a pre/post command to the `ansible-runner` or `merge-stack-and-config` scripts. (To learn more about pre/post commands, see [here](/reference/ci-cd-pipelines/concepts/cycloid-toolkit.md#running-pre-or-post-commands-with-toolkit-scripts))

pipeline.yaml

```
  - &run-ansible-from-bastion
    config:
      platform: linux
      image_resource:
        type: registry-image
        source:
          repository: cycloid/cycloid-toolkit
          tag: "latest"
      run:
        path: /bin/bash
        args:
          - '-exc'
          - |
            cat > ansible-playbook/inventory_file <<EOF
            [webservers]
            foo.example.com
            bar.example.com

            [dbservers]
            one.example.com
            EOF

            /usr/bin/ansible-runner
      caches:
        - path: ansible-playbook/roles
      inputs:
      - name: merged-stack
        path: ansible-playbook
```

Then add the `ANSIBLE_INVENTORY` environment variable as run-ansible task params:

pipeline.yaml

```
      - task: run-ansible
        <<: *run-ansible-from-bastion
        params:
          ANSIBLE_INVENTORY: inventory_file      # Relative path refer to **ANSIBLE_PLAYBOOK_PATH**
          ...
```

#### 3 - Provide addresses as command-line arguments[​](#3---provide-addresses-as-command-line-arguments "Direct link to 3 - Provide addresses as command-line arguments")

This method is primarily used for testing purposes, but you can potentially extend it using the [load\_var](/reference/ci-cd-pipelines/concepts/pipeline.md#load_var-load-a-variable-from-a-file) feature in our pipelines.

This approach relies on the ability to pass a list of host addresses directly using the command-line `-i` argument. Instead of specifying a host file path, you provide a comma-separated list of host addresses. ([Ansible official documentation](https://docs.ansible.com/ansible/latest/plugins/inventory.html#inventory-plugins))

pipeline.yaml

```
      - task: run-ansible
        <<: *run-ansible-from-bastion
        params:
          ANSIBLE_EXTRA_ARGS: "-i host1,"        # multiple hosts: -i 'host1, host2'
          ...
```

### Troubleshooting inventories[​](#troubleshooting-inventories "Direct link to Troubleshooting inventories")

If you would like to have a glimpse into how the dynamic inventory plugin or script is organizing your instances into groups, you can use the `ansible-inventory` command line:

* ansible
* output logs

```
run:
  path: /bin/bash
  args:
    - '-exc'
    - |
      /usr/bin/ansible-runner-inventory

      # Same way you would run the ansible runner
      # /usr/bin/ansible-runner
```

```
@all:
  |--@linux:
  |  |--server3.example.com
  |  |--server4.example.com
  |--@ungrouped:
  |--@windows:
  |  |--server5.example.com
  |  |--server6.example.com
```

## Use Cycloid credential in Ansible through the pipeline[​](#use-cycloid-credential-in-ansible-through-the-pipeline "Direct link to Use Cycloid credential in Ansible through the pipeline")

The pipeline engine integrates Cycloid credentials natively, facilitating their use within Ansible by passing them through the pipeline.

To begin, define a stackforms credential widget to capture the credential input from users. This credential will then be provided as an Ansible extra variable during runtime.

It's important to note that the credential will be utilized as a pipeline variable and forwarded from the pipeline to Ansible. Therefore, it's crucial to ensure the correct use of pipeline technology in stackforms.

.forms.yml

```

...
      technologies: [pipeline]
      vars:
        - name: "My cred"
          key: my_credential
          widget: cy_cred
```

Once configured, you can use this credential directly within the pipeline as an environment variable for the ansible-runner script. For instance, you can specify it in `EXTRA_ANSIBLE_VARS`:

pipeline.yaml

```
      - task: run-ansible
        <<: *run-ansible-from-bastion
        params:
...
          AWS_SECRET_ACCESS_KEY: ((my_aws_secret_key))    # This could be also a credential
          EXTRA_ANSIBLE_VARS:
            my_credential: ((my_credential)) # Referencing the defined credential
```

With this setup, you can utilize the `{{ my_credential }}` variable seamlessly within your Ansible playbooks.

## Use Terraform outputs as Ansible variables[​](#use-terraform-outputs-as-ansible-variables "Direct link to Use Terraform outputs as Ansible variables")

This topic is handled in [variables-sharing section](/reference/ci-cd-pipelines/concepts/tools-integration/terraform.md#sharing-variables-between-terraform-and-ansible)


---

# Interpolation

Cycloid introduced a


---

# Terraform

To run Terraform within a pipeline, we typically recommend following the [stack concept](/reference/stacks/concepts/stack-concept.md) and leveraging the community Concourse Terraform resource.

Running Terraform in a pipeline requires two key steps:

1. Define how and where to store the remote state file (`tfstate`) and configure the Terraform resource. It is recommended to utilize Cycloid Asset Inventory for this purpose.
2. Create Terraform plan and apply jobs to utilize the defined resource effectively.

### 1 - Storing the `tfstate` File and Configuring Terraform Resource[​](#1---storing-the-tfstate-file-and-configuring-terraform-resource "Direct link to 1---storing-the-tfstate-file-and-configuring-terraform-resource")

To store the remote `tfstate` file, we typically recommend using [Cycloid Asset Inventory](/reference/inventory/concepts.md#how-to-use-it-in-a-pipelines-) due to its additional features. However, you can also use any object storage or compatible Terraform remote backend.

The resource configuration consists of two crucial parts:

* **backend\_config**: Contains the configuration and access keys used by Terraform to store the `tfstate` file.
* **vars/env**: Includes input variables and cloud provider access keys required to execute Terraform commands.

Below are a few examples of Terraform resource definitions and configurations for different backend storage options and access to cloud providers.

* Cycloid asset inventory (recommended)
* Aws S3 bucket
* GCP object storage
* Azure storage account

Based on Terraform HTTP backend, more information on how to configure it can be found [here](/reference/inventory/concepts.md#how-to-use-it-in-a-pipelines-)

pipeline.yaml

```
resource_types:
- name: terraform
  type: registry-image
  source:
    repository: cycloid/terraform-resource

resources:
- name: tfstate
  type: terraform
  icon: terraform
  source:
    backend_config:
      address: '($ cycloid_api_url $)/inventory?jwt=($ inventory_jwt $)'
      ## skip_cert_verification needs to be enabled when using self signed certificates.
      # skip_cert_verification: true
    backend_type: http
    env_name: default

    #
    # Cloud provider dependent section
    #

    # AWS example
    vars:
      access_key: ((aws_access_key))
      secret_key: ((aws_secret_key))
      aws_region: ((aws_default_region))

    # GCP example
    vars:
      gcp_project: ((gcp_project))
      gcp_zone: ((gcp_zone))
    env:
      GOOGLE_PROJECT: ((gcp_project))
      GOOGLE_ZONE: ((gcp_zone))
      GOOGLE_CREDENTIALS: ((gcp_credentials_json))

    # Azure example
    vars:
      azure_resource_group_name: ((azure_resource_group_name))
      azure_location: ((azure_location))
      azure_env: ((azure_env))
      azure_cred: ((azure_cred))
      env: ((env))
      project: ((project))
      customer: ((customer))
```

pipeline.yaml

```
resource_types:
- name: terraform
  type: registry-image
  source:
    repository: cycloid/terraform-resource

resources:
- name: tfstate
  type: terraform
  icon: terraform
  source:
    env_name: ((env))
    backend_type: s3
    backend_config:
      bucket: ((terraform_storage_bucket_name))
      key: terraform.tfstate
      workspace_key_prefix: ((project))
      region: ((aws_default_region))
      access_key: ((aws_access_key))
      secret_key: ((aws_secret_key))

    # Cloud provider access (To run Terraform)
    vars:
      access_key: ((aws_access_key))
      secret_key: ((aws_secret_key))
      aws_region: ((aws_default_region))
```

pipeline.yaml

```
resource_types:
- name: terraform
  type: registry-image
  source:
    repository: cycloid/terraform-resource

resources:
- name: tfstate
  type: terraform
  icon: terraform
  source:
    env_name: ((env))
    backend_type: gcs
    backend_config:
      bucket: ((terraform_storage_bucket_name))
      prefix: ((project))/((env))
      credentials: ((gcp_credentials_json))

    # Cloud provider access (To run Terraform)
    vars:
      gcp_project: ((gcp_project))
      gcp_zone: ((gcp_zone))
    env:
      GOOGLE_PROJECT: ((gcp_project))
      GOOGLE_ZONE: ((gcp_zone))
      GOOGLE_CREDENTIALS: ((gcp_credentials_json))
```

pipeline.yaml

```
resource_types:
- name: terraform
  type: registry-image
  source:
    repository: cycloid/terraform-resource

resources:
- name: tfstate
  type: terraform
  icon: terraform
  source:
    env_name: ((env))
    backend_type: azurerm
    backend_config:
      container_name: ((terraform_storage_container_name))
      key: ((terraform_storage_container_path))/((project))-((env)).tfstate
      storage_account_name: ((terraform_storage_account_name))
      access_key: ((terraform_storage_access_key))

    # Cloud provider access (To run Terraform)
    vars:
      azure_resource_group_name: ((azure_resource_group_name))
      azure_location: ((azure_location))
      azure_env: ((azure_env))
      azure_cred: ((azure_cred))
```

### 2 - Creating Terraform Plan and Apply Jobs[​](#2---creating-terraform-plan-and-apply-jobs "Direct link to 2 - Creating Terraform Plan and Apply Jobs")

The next step to integrate Terraform into a pipeline typically involves creating two jobs: one for Terraform plan and another for apply. Both jobs utilize the previously configured Terraform resource.

Additionally, it's important to note the usage of `merge-stack-and-config` for stacks that follow our concept of splitting configuration and stack code. This ensures that configuration changes are seamlessly integrated with the stack code during the pipeline execution.

* Rendering
* Code

![img](/assets/images/pipeline-terraform-jobs-b4ca1263beaf7271df8732362e458a90.png)

pipeline.yaml

```
# YAML anchors
shared:
  - &merge-stack-and-config
    platform: linux
    image_resource:
      type: registry-image
      source:
        repository: cycloid/cycloid-toolkit
        tag: "latest"
    run:
      path: /usr/bin/merge-stack-and-config
    outputs:
    - name: merged-stack
      path: "merged-stack"

jobs:
- name: terraform-plan
  serial: true
  serial_groups: [terraform]
  max_in_flight: 1
  build_logs_to_retain: 10
  plan:
    - do:
      - get: git_stack
        params: {depth: 1}
        trigger: true
      - get: git_config
        params: {depth: 1}
        trigger: true

      - task: merge-stack-and-config
        config:
          <<: *merge-stack-and-config
          inputs:
          - name: git_config
            path: "config"
          - name: git_stack
            path: "stack"
        params:
          CONFIG_PATH: ($ .project $)/terraform/($ .env $) # This value depend of the stack configuration in .cycloid.yaml file
          STACK_PATH: ($ .stack_path $)/terraform

      - put: tfstate
        params:
          plan_only: true
          terraform_source: merged-stack/

- name: terraform-apply
  serial: true
  serial_groups: [terraform]
  max_in_flight: 1
  build_logs_to_retain: 10
  plan:
    - do:
      - get: git_stack
        trigger: false
        passed:
          - terraform-plan
      - get: git_config
        trigger: false
        passed:
          - terraform-plan
      - get: tfstate
        trigger: false
        passed:
          - terraform-plan

      - task: merge-stack-and-config
        config:
          <<: *merge-stack-and-config
          inputs:
          - name: git_config
            path: "config"
          - name: git_stack
            path: "stack"
        params:
          CONFIG_PATH: ($ .project $)/terraform/($ .env $)
          STACK_PATH: ($ .stack_path $)/terraform

      - put: tfstate
        params:
          plan_run: true
          terraform_source: merged-stack/
```

As shown, the Terraform apply job specifies all resources with the `passed: [terraform-plan]` parameter to ensure that all changes have been planned before applying them. Additionally, notice that there is no `trigger: true` setting on the apply job. This is a common practice in Terraform workflows to require the end user to access the pipeline interface and manually trigger the Terraform apply job after reviewing the Terraform plan output.

### How to Destroy Infrastructure Created by Terraform[​](#how-to-destroy-infrastructure-created-by-terraform "Direct link to How to Destroy Infrastructure Created by Terraform")

To remove all resources created by Terraform, you can create a dedicated job similar to the Terraform apply job, but using [Terraform destroy](https://www.terraform.io/cli/commands/destroy) instead.

Here's an example of how to set up a Terraform destroy job in your pipeline:

* Rendering
* Code

![img](/assets/images/pipeline-terraform-destroy-job-8da016a183e59c2752b4161924637fb0.png)

pipeline.yaml

```
- name: terraform-destroy
  serial: true
  serial_groups: [terraform]
  max_in_flight: 1
  build_logs_to_retain: 10
  plan:
    - do:
        - get: git_stack-terraform
          params: {depth: 1}
          trigger: false
        - get: git_config-terraform
          params: {depth: 1}
          trigger: false
        - task: merge-stack-and-config
          config:
            <<: *merge-stack-and-config
            inputs:
            - name: git_config
              path: "config"
            - name: git_stack
              path: "stack"
          params:
          CONFIG_PATH: ($ .project $)/terraform/($ .env $)
          STACK_PATH: ($ .stack_path $)/terraform

        - put: tfstate
          params:
            action: destroy
            terraform_source: merged-stack/
          get_params:
            action: destroy
```

## Using Cycloid Credentials in Terraform via the Pipeline[​](#using-cycloid-credentials-in-terraform-via-the-pipeline "Direct link to Using Cycloid Credentials in Terraform via the Pipeline")

The pipeline engine integrates native support for Cycloid credentials. The simplest method to utilize Cycloid credentials in Terraform is to pass them through the pipeline.

Here’s how to proceed:

1. **Define a StackForms Credential Widget**: Begin by defining a StackForms credential widget. Users will securely input their credentials through this widget.

2. **Pipeline Variable**: Capture the credential input as a pipeline variable. This variable will then be forwarded to Terraform as an input variable.

Define a StackForms Credential Widget:

.forms.yml

```

...
      technologies: [pipeline]
      vars:
        - name: "My cred"
          key: my_terraform_credential
          widget: cy_cred
```

Then, the next step is to configure the pipeline and the Terraform resource to include the content of this credential as a Terraform input variable.

Edit the pipeline template and add a new Terraform input variable that includes the StackForms credential widget under the `vars` section.

pipeline.yaml

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

In this example, we update the Terraform resource configuration to include a `my_terraform_credential` Terraform variable that will hold our credential data. This setup is analogous to using `terraform -var my_terraform_credential=my_cred_datas` in a command-line interface.

After making this adjustment, when the pipeline executes, this new variable is passed to Terraform as an input variable.

On the **Terraform side** ensure you define a dedicated [input variable](https://developer.hashicorp.com/terraform/language/values/variables) by following these steps

1. Define your credential variable in the Terraform root level:

terraform/variables.tf

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

2. You can then use this variable directly within the Terraform module call or throughout your Terraform configuration.

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
}
```

## Sharing Variables between Terraform and Ansible[​](#sharing-variables-between-terraform-and-ansible "Direct link to Sharing Variables between Terraform and Ansible")

### Why?[​](#why "Direct link to Why?")

When building a stack that involves Terraform for infrastructure provisioning and Ansible for configuring services on instances (e.g., setting up a Wordpress website), it's crucial to share information such as the address of Amazon RDS databases or Amazon ElastiCache instances.

This information can be predefined using tools like Amazon Route53 for DNS resolution, Consul for service discovery, or by defining shared variables that both Terraform and Ansible can access. This ensures seamless coordination between provisioning infrastructure and configuring services, enabling efficient management and operation of your stack.

### How?[​](#how "Direct link to How?")

If you adhere to the Cycloid stack concept and utilize the `merge-stack-and-config` script, you can seamlessly share information between Terraform and Ansible. This script automatically retrieves Terraform information from the `tfstate` file and converts it into Ansible variables based on Terraform outputs, as outlined in [Terraform outputs documentation](https://www.terraform.io/language/values/outputs).

Here’s how it works:

* After running Terraform using the appropriate configuration, include a call to `merge-stack-and-config` with the `tfstate` input.
* The script will automatically convert Terraform outputs into Ansible variables (See `extract-terraform-outputs` script for more details)

### Example in the Magento stack[​](#example-in-the-magento-stack "Direct link to Example in the Magento stack")

1. To do that you first have to define a Terraform output:

[stack-magento/terraform/outputs.tf](https://github.com/cycloid-community-catalog/stack-magento/blob/master/terraform/outputs.tf#L13-L15)

outputs.tf

```
output "rds_address" {
  value = "${module.magento.rds_address}"
}
```

2. Then in the Ansible job of your pipeline, ensure you get the output of Terraform job.

[stack-magento/pipeline/pipeline.yml](https://github.com/cycloid-community-catalog/stack-magento/blob/master/pipeline/pipeline.yml#L309-L314)

And add this as input for the merge-stack-and-config task. By providing a “terraform” directory as input, the merge task will provide all Terraform outputs to Ansible as global variables in `group_vars/all`

[stack-magento/pipeline/pipeline.yml](https://github.com/cycloid-community-catalog/stack-magento/blob/master/pipeline/pipeline.yml#L336-L337)

![img](/assets/images/pipeline-ansible-run-terraform-bcd6ecb0c20fa632ab1442c97060a9a7.png)

pipeline.yaml

```
- task: merge-stack-and-config
   config:
     <<: *merge-stack-and-config
     inputs:
     - name: git_config-ansible
       path: "config"
     - name: git_stack-ansible
       path: "stack"
     - name: tfstate
       path: "terraform"
   params:
     CONFIG_PATH: ($ .project $)/ansible
     STACK_PATH: ($ .stack_path $)/ansible
```

3. Use those new variables in Ansible

[stack-magento/ansible/environments/default\_front.yml](https://github.com/cycloid-community-catalog/stack-magento/blob/master/ansible/environments/default_front.yml#L33)

ansible variables

```
magento_db_host: "{{ rds_address | default('localhost') }}"
```


---

# Workers

A Cycloid worker is an essential component that executes the tasks defined in a pipelines. You can have one or several workers, the number of workers and CPU/memory sizing could vary based on the tasks you are going to execute.

There are several ways to deploy your own workers, it can differ a bit if you subscribe to [Cycloid Platform](https://www.cycloid.io/devops-framework):

* SaaS console [console.cycloid.io](https://console.cycloid.io/)
* Dedicated or On-premises setup

All methods rely on the source code of the public [stack-external-worker](https://github.com/cycloid-community-catalog/stack-external-worker).

## Prerequisites[​](#prerequisites "Direct link to Prerequisites")

In terms of network, workers initiate the connection with the scheduler:

![img](/assets/images/onprem-workers-cc103401cbb7f3a850d4d19edd960b93.png)

This means if the worker is running in your own private network, there is no inbound network traffic to allow. A common scenario is to deploy a worker in a network close to your target infrastructure, simplifying network requirements for tools like Ansible.

Cycloid workers require outbound traffic to the Cycloid scheduler. Additionally, depending on your pipeline jobs, workers generally need access to Docker Hub for resource images and to your code repository.

### Exhaustive List of Outgoing Traffic from the Workers[​](#exhaustive-list-of-outgoing-traffic-from-the-workers "Direct link to Exhaustive List of Outgoing Traffic from the Workers")

* SaaS console
* On-premises

| **Required** | **Service**       | **Destination**                        |
| ------------ | ----------------- | -------------------------------------- |
| `yes`        | `Scheduler API`   | `https://scheduler.cycloid.io`         |
| `yes`        | `Scheduler`       | `scheduler.cycloid.io:32223`           |
| `yes`        | `Docker registry` | `https://index.docker.io`, `docker.io` |
| `yes`        | `Cycloid stack`   | `https://github.com/`                  |

| **Required** | **Service**       | **Destination**                                  |
| ------------ | ----------------- | ------------------------------------------------ |
| `yes`        | `Scheduler API`   | Concourse web `https://<cycloid_scheduler>:8443` |
| `yes`        | `Scheduler`       | Concourse TSA `<cycloid_scheduler>:2222`         |
| `yes`        | `Docker registry` | `https://index.docker.io`, `docker.io`           |
| `yes`        | `Cycloid stack`   | `https://github.com/`                            |

## Type of Workers[​](#type-of-workers "Direct link to Type of Workers")

**Scoped Workers Pool:** Using the Cycloid SaaS platform, worker pools are scoped to an organization. This means that all pipelines of an organization will run on workers attached to it. If you create another organization, you will need to create a separate worker pool for that organization.

> A worker pool can be attached to only one organization at a time.

**Global Worker Pool:** If you own your dedicated Cycloid platform, you can attach a pool of workers that will be used by all organizations. This can be convenient for providing a shared pool of workers for all your users.

note

A pool of scoped workers can be attached to only one organization, while a global worker pool is attached to all organizations. There is no way to attach a pool of workers to only a specified list of organizations.

Keep in mind that it's quite easy to attach either a scoped or global worker pool in Cycloid, so you can change your configuration as needed.

## Worker tags[​](#worker-tags "Direct link to Worker tags")

At setup you can define a tag for a worker. By doing that a worker with a tag will execute only pipeline jobs defined with the same tag. Tagging a worker allows you to specify which workers should execute certain tasks, ensuring that specific jobs run on appropriate or specialized workers. This can be useful for tasks that require particular dependencies, software versions, or hardware capabilities.

**Example Use Case:** If you have a pipeline task that performs heavy I/O operations, you can tag a worker with "high-iops" and configure the corresponding tasks in your pipeline to only run on workers with this tag. This ensures that the task runs on workers equipped with high-performance disks, providing the necessary IOPS (Input/Output Operations Per Second) to handle intensive data processing efficiently.

## How to deploy[​](#how-to-deploy "Direct link to How to deploy")

| Provider             | Information                                                                                                               |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| ![](/img/aws.png)    | [On AWS with CloudFormation](/reference/ci-cd-pipelines/concepts/workers/aws.md)                                          |
| ![](/img/azure.png)  | [On Azure with Resource Manager Template](/reference/ci-cd-pipelines/concepts/workers/azure.md)                           |
| ![](/img/fe.png)     | [On Flexible Engine with Resource Template Service (RTS)](/reference/ci-cd-pipelines/concepts/workers/flexible-engine.md) |
| ![](/img/gcp.png)    | [On GCP with Deployment manager](/reference/ci-cd-pipelines/concepts/workers/gcp.md)                                      |
| ![](/img/onprem.png) | [On baremetal servers](/reference/ci-cd-pipelines/concepts/workers/baremetal.md)                                          |
| ![](/img/docker.png) | [Locally using Docker (DEVELOPMENT PURPOSES ONLY)](/reference/ci-cd-pipelines/concepts/workers/docker.md)                 |

## Troubleshooting[​](#troubleshooting "Direct link to Troubleshooting")

If your worker is not running correctly, you can follow the [Troubleshooting section](/reference/ci-cd-pipelines/concepts/workers/troubleshooting.md).


---

# On Amazon Web Services with CloudFormation

![](/img/aws.png)

The CloudFormation deployment is based on a template located under our [stack-external-worker](https://github.com/cycloid-community-catalog/stack-external-worker/blob/master/extra/aws/external-worker-aws-cf-template.yaml) git repository.

The CloudFormation stack will create an AWS autoscaling group with EC2 instances as Cycloid workers.

Follow these steps to create a CloudFormation stack:

1. Connect on [http://console.cycloid.io](https://console.cycloid.io/dashboard).
2. Click on your top right **profile picture**, and select `Organization settings`

![](/img/org_settings.png)

1. Go into the `Workers` tab and select `Amazon Web Services`.
2. Select the region in which you want to deploy the workers.
3. Click on the button `Launch CloudFormation Stack`. It will redirect you to Amazon Console. (**See comments at the end of the page**)

![cloudformation-stack](/assets/images/cloudformation-stack-c308557faac8907b68a9613f5d6da746.png)

1. Configure the CloudFormation stack to match your AWS configuration
2. Select the checkbox `I acknowledge that AWS CloudFormation might create IAM resources.` The stack will create an IAM role for the workers.
3. Click on `Create` button to create the stack.

After the deployment of the CloudFormation stack, get back on the `Workers` tab in the Cycloid dashboard. It will display all your connected workers and their status:

![worker-status](/assets/images/worker-status-cb230020b340f83b1996c95b342a82f1.png)

**Note:** Sometimes, CloudFormation returns an error 400 (Bad Request), we are aware about of this and we are working with AWS to help them to fix it. Meanwhile, there are two options to solve it:

* Once you clicked on the button `Launch CloudFormation Stack` and have realized that you have a blank page or similar, you can copy the url and paste it in a new tab, then you will be redirected to the correct page.
* Go to [CloudFormation home page](https://console.aws.amazon.com/cloudformation/home), then click back on `Launch CloudFormation Stack` button and it will work as expected.

## Change Cycloid worker size[​](#change-cycloid-worker-size "Direct link to Change Cycloid worker size")

1. Connect on [AWS Management Console](https://aws.amazon.com/fr/console/)

2. Go on the CloudFormation service page.

3. Select the `cycloid-ci-workers` stack and click on the top right `Update` button.

   <!-- -->

   * Select the `Use current template` checkbox.
   * Click on `next`.

4. Select the desired `InstanceType`.

5. Click `next` up to the `Update stack` button.

## Update from the latest version of the stack[​](#update-from-the-latest-version-of-the-stack "Direct link to Update from the latest version of the stack")

1. Connect on [AWS Management Console](https://aws.amazon.com/fr/console/)

2. Go on the CloudFormation service page.

3. Select the `cycloid-ci-workers` stack and click on the top right `Update` button.

   <!-- -->

   * Select the `Replace current template` checkbox.
   * Click on `Amazon S3 URL`.
   * Put the following url `https://s3-eu-west-1.amazonaws.com/cycloid-cloudformation/external-worker-aws-cf-template.yaml`.
   * Click `next` up to the `Update stack` button.

## Troubleshooting[​](#troubleshooting "Direct link to Troubleshooting")

If your worker is not running correctly, you can follow the [Troubleshooting section](/reference/ci-cd-pipelines/concepts/workers/troubleshooting.md).


---

# On Microsoft Azure with Resource Manager Template

![](/img/azure.png)

The Azure Resource Manager template is located under our [stack-external-worker](https://github.com/cycloid-community-catalog/stack-external-worker/blob/master/extra/azure/external-worker-azure-rm-template.json) git repository.

The template will create an Azure Virtual Machine Scale Set of Cycloid workers. The default values are already pre-filled to deploy and connect workers on our public SaaS, then you will be able to modify them according to your needs.

![azure-resource-manager-template](/assets/images/azure-resource-manager-template-08d6b832072dc850ff27efcd4fe82300.png)

Follow these steps to deploy the Azure Resource Manager template:

1. Connect on [http://console.cycloid.io](https://console.cycloid.io/dashboard).
2. Click on your top right **profile picture**, and select `Organization settings`

![](/img/org_settings.png)

1. Go into the `Workers` tab and select `Microsoft Azure`.
2. Follow the different steps and hit the `Deploy to Azure` button.
3. Configure the Custom deployment to match your needs
4. Click on the `Purchase` button to create the stack.

After the Custom template deployment, go to the `Workers` tab in the Cycloid dashboard. It will display all your connected workers and their status:

![worker-status](/assets/images/worker-status-cb230020b340f83b1996c95b342a82f1.png)

## Troubleshooting[​](#troubleshooting "Direct link to Troubleshooting")

### Common template errors[​](#common-template-errors "Direct link to Common template errors")

If your deployment from a Microsoft Template failed, please check the `Status message` from **Operation details**

**InvalidTemplate**

Example:

```
{
    "status": "Failed",
    "error": {
        "code": "InvalidTemplate",
        "message": "Unable to process template language expressions for resource '/subscriptions/abcde1234-1234-1a23-2b3b-1a21234567ab/resourceGroups/cycloid-demo/providers/Microsoft.Compute/virtualMachineScaleSets/cycloid-demo-cycloid-ci-workers-prod' at line '496' and column '9'. 'Unable to evaluate template language function 'resourceId': function requires exactly one multi-segmented argument which must be resource type including resource provider namespace. Current function arguments 'Microsoft.Network/virtualNetworks/subnets,/subscriptions/abcde1234-1234-1a23-2b3b-1a21234567ab/resourceGroups/cycloid-demo/providers/Microsoft.Network/virtualNetworks/cycloid-virtual-network,/subscriptions/abcde1234-1234-1a23-2b3b-1a21234567ab/resourceGroups/cycloid-demo/providers/Microsoft.Network/virtualNetworks/cycloid-virtual-network/subnets/cycloid-subnet'. Please see https://aka.ms/arm-template-expressions/#resourceid for usage details.'",
        "additionalInfo": [
            {
                "type": "TemplateViolation",
                "info": {
                    "lineNumber": 496,
                    "linePosition": 9,
                    "path": ""
                }
            }
        ]
    }
}
```

Reason: The given `virtualNetworkName` or `subnetName` use an invalid format. The expected format is the **name** of the resources. The most common mistake from user is to specify the ID URL instead of only the name.

Solution: Provide only the resource name as a simple string.

Wrong : `/subscriptions/.../resourceGroups/.../providers/Microsoft.Network/virtualNetworks/.../subnets/cycloid-subnet` Good: `cycloid-subnet`

**InvalidResourceReference**

Example:

```
{
    "status": "Failed",
    "error": {
        "code": "InvalidResourceReference",
        "message": "Resource /subscriptions/abcde1234-1234-1a23-2b3b-1a21234567ab/resourceGroups/.../providers/Microsoft.Network/virtualNetworks/MY-WRONG-NETWORK referenced by resource /subscriptions/abcde1234-1234-1a23-2b3b-1a21234567ab/resourceGroups/.../providers/Microsoft.Compute/virtualMachineScaleSets/cycloid-demo-cycloid-ci-workers-prod was not found. Please make sure that the referenced resource exists, and that both resources are in the same region.",
        "details": [
            {
                "code": "NotFound",
                "message": "Resource /subscriptions/abcde1234-1234-1a23-2b3b-1a21234567ab/resourceGroups/.../providers/Microsoft.Network/virtualNetworks/MY-WRONG-NETWORK not found."
            }
        ]
    }
}
```

Reason: A Resource mentioned is not found on Azure. In this example, the `virtualNetworks` name provided "MY-WRONG-NETWORK" doesn't exist on Azure cloud.

Solution: make sure the resource name provided is correctly spelled.

If your worker is not running correctly, you can follow the [Troubleshooting section](/reference/ci-cd-pipelines/concepts/workers/troubleshooting.md).


---

# Deploy a baremetal Cycloid worker

![](/img/onprem.png)

To run a Cycloid worker on a bare metal or on-premises server, it is currently required to provide a debian-based operating system.

Follow these steps to create a worker:

1. Connect on [http://console.cycloid.io](https://console.cycloid.io/dashboard).
2. Click on your top right **profile picture**, and select `Organization settings`

![](/img/org_settings.png)

1. Go into the `Workers` tab and select `Bare Metal or other cloud`.
2. Follow the different steps.
3. Connect to your server and execute the generated commands to start the setup of the worker.

After the deployment, go on `Workers` tab in the Cycloid dashboard. It will display all your connected workers and their statuses:

![worker-status](/assets/images/worker-status-cb230020b340f83b1996c95b342a82f1.png)

## Troubleshooting[​](#troubleshooting "Direct link to Troubleshooting")

If your worker is not running correctly, you can follow the [Troubleshooting section](/reference/ci-cd-pipelines/concepts/workers/troubleshooting.md).


---

# Deploy a local Cycloid worker using Docker

![](/img/docker.png)

tip

This solution is for DEVELOPMENT PURPOSES ONLY. For production worker, we advice you to use the dedicated setup for each cloud providers.

To run a local Cycloid worker it requires to have a machine with Docker installed on it.

Follow these steps to create a local worker based on Docker:

1. Connect on [http://console.cycloid.io](https://console.cycloid.io/dashboard).
2. Click on your top right **profile picture**, and select `Organization settings`

![](/img/org_settings.png)

1. Go into the `Workers` tab and select `Docker`.
2. Follow the different steps.

After the deployment, go on `Workers` tab in the Cycloid dashboard. It will display all your connected workers and their statuses:

![worker-status](/assets/images/worker-status-cb230020b340f83b1996c95b342a82f1.png)


---

# On Flexible engine with Resource Template Service (RTS)

![](/img/fe.png)

Download our Flexible engine Resource Template [flexible-engine.zip](https://cycloid-cloudformation.s3-eu-west-1.amazonaws.com/flexible-engine.zip) S3 bucket.

The template will create compute engine instances of Cycloid workers. The default values are already pre-filled to deploy and connect workers on our public SaaS, then you will be able to modify them according to your needs.

Follow these steps to deploy the Flexible engine Resource template:

1. Connect on [http://console.cycloid.io](https://console.cycloid.io/dashboard).
2. Click on your top right **profile picture**, and select `Organization settings`

![](/img/org_settings.png)

1. Go into the `Workers` tab and select `Flexible Engine`.
2. Connect on Flexible engine console <https://console.prod-cloud-ocb.orange-business.com>.
3. Go in Resource Template Service section (RTS)

![](/img/rts.png)

1. Click on the following button

![](/img/fe-stack-create.png)

1. Select `Upload template` and upload the previously downloaded `flexible-engine.zip` file.

   <!-- -->

   * Click on `upload`
   * And select the `main.yaml` file
   * Click `next` ![RTS](/assets/images/rts-upload-09f6e23bd404d22bbaac1796b428d9c0.png)

2. Click on `Submit` button to create the stack.

After the Custom template deployment, go to the `Workers` tab in the Cycloid dashboard. It will display all your connected workers and their status:

![worker-status](/assets/images/worker-status-cb230020b340f83b1996c95b342a82f1.png)

## Troubleshooting[​](#troubleshooting "Direct link to Troubleshooting")

If your worker is not running correctly, you can follow the [Troubleshooting section](/reference/ci-cd-pipelines/concepts/workers/troubleshooting.md).


---

# On Google Cloud Platform with Deployment manager

![](/img/gcp.png)

The Deployment manager is based on a template located under our [stack-external-worker](https://github.com/cycloid-community-catalog/stack-external-worker/blob/master/extra/gcp) git repository.

The Deployment manager stack will create an GCP autoscaler with Cycloid workers on Compute engine. The default values are already pre-filled to deploy and connect workers on our public SaaS, then you will be able to modify them according to your needs.

![](/img/gcp-deployment-manager.png)

Before you start, make sure you installed `gcloud` and configured it. [Starting with deployment manager](https://cloud.google.com/deployment-manager/docs/step-by-step-guide/installation-and-setup)

Follow these steps to create a Deployment manager stack:

1. Connect on [http://console.cycloid.io](https://console.cycloid.io/dashboard).
2. Click on your top right **profile picture**, and select `Organization settings`

![](/img/org_settings.png)

1. Go into the `Workers` tab and select `Google Cloud Platform`.
2. Follow the different steps and run the commands (gcloud deploy CLI help [here](https://cloud.google.com/deployment-manager/docs/step-by-step-guide/deploy-your-resources))

Note

You can edit the `external-worker-gcp-template.yaml` file to select the number of deployed worker or the compute size.

```
instanceType: n1-standard-4
numberOfWorkers: 1
```

After the deployment of the stack, go on `Workers` tab in the Cycloid dashboard. It will display all your connected workers and their status:

![worker-status](/assets/images/worker-status-cb230020b340f83b1996c95b342a82f1.png)

## Troubleshooting[​](#troubleshooting "Direct link to Troubleshooting")

If your worker is not running correctly, you can follow the [Troubleshooting section](/reference/ci-cd-pipelines/concepts/workers/troubleshooting.md).


---

# Cycloid workers known errors

\# Worker iptables issue on Debian 12

Related to this bug <https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=998716> on some Cloud provider Debian 12 image is not fully working.

## The error message[​](#the-error-message "Direct link to The error message")

This trigger the following Concourse errors:

**itables legacy**

> error: Exit trace for group: garden exited with error: Exit trace for group: containerd-garden-backend exited with error: setup host network failed: appending accept rule for RELATED & ESTABLISHED connections failed: running \[/usr/sbin/ --ctstate RELATED,ESTABLISHED -j ACCEPT --wait]: exit status 1: Warning: Extension conntrack revision 0 not supported, missing kernel module? iptables: No chain/target/match by that name.

**new iptables**

> error: Exit trace for group: garden exited with error: Exit trace for group: containerd-garden-backend exited with error: setup host network failed: appending accept rule for RELATED & ESTABLISHED connections failed: running \[/usr/sbin/ --ctstate RELATED,ESTABLISHED -j ACCEPT --wait]: exit status 4: Warning: Extension conntrack revision 0 not supported, missing kernel module? iptables v1.8.9 (nf\_tables): RULE\_APPEND failed (No such file or directory): rule in chain CONCOURSE-OPERATOR

## Identify[​](#identify "Direct link to Identify")

Loading the required conntrack kernel module should fail

```
modprobe nf_conntrack
```

## Source of the error[​](#source-of-the-error "Direct link to Source of the error")

To sum up the issue the kernel modules source code on disk does not match the running kernel. Concourse require the conntrack kernel module to be loaded. If you try to load this module `modprobe nf_conntrack` the following error might appear in dmesg logs

```
[57802.094590] missing module BTF, cannot register kfuncs
[58115.134821] BPF:      type_id=25464 bits_offset=0
[58115.138633] BPF:  
[58115.144178] BPF: Invalid name
[58115.147384] BPF: 
[58115.150361] failed to validate module [nf_conntrack] BTF: -22
```

## Resolution[​](#resolution "Direct link to Resolution")

Update the initrd of your server and reboot. After the reboot you should be able to load the conntrack kernel module

```
update-initramfs -u
# Then reboot
```

Note: On some distrib is you still have iptables related issue you can try to also switch back to iptables legacy using:

```
update-alternatives --set iptables /usr/sbin/iptables-legacy
update-alternatives --set ip6tables /usr/sbin/ip6tables-legacy
```


---

# Troubleshooting

## Basics[​](#basics "Direct link to Basics")

At boot Cycloid worker run [startup.sh](https://github.com/cycloid-community-catalog/stack-external-worker/blob/master/extra/startup.sh) script . This script installs the worker using Ansible.

If your worker does not appear in the list of Cycloid workers, connect via SSH to the worker and refer to the following sections.

To connect using **SSH** on a worker, the SSH user depend on Cloud provider base images. By default we use Debian images and usual users are:

* Azure: user cycloid
* AWS: user admin
* GCP: gcloud command

## First aid[​](#first-aid "Direct link to First aid")

**Step 1) Check the boot script status**

The `startup.sh` script is run at boot using cloud init. The setup logs can be found in either of those 2 files:

```
/var/log/cloud-init-output.log
/var/log/user-data.log
```

Check if there are any errors, If your setup is successful you should see Ansible summary log line without any `failed` statement

![worker-ansible-setup](data:image/png;base64,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izt51ZVKfsni8wPefPPNH3/8MT09XalUqn1+t7W19ZYtWy5fviwIgnRgfZlvVC0LC4uvvvrqt99+S09P37t3b53cSFZX1D4/QL4mP/74Y7WjZlf6XrWryS5duvz888/ig5LHjBkjfYavTtaz/A6H6vkB5bm9NX79Fd9/D319zJqlfqR+8RyF+ISAgQOxaVPpE7rfe698OfLRF5Xsqo0+S7XLV82bN1+5cmVcXFxqaurFixfDwsLc3d0rza4pX8nn2Ia2LVSbNzp16qT6vqNGjQoPD99f9uNd7e+Rvb19YGBgSkqKmLIqnU+rdevrWCto6r8REf3N/Pwzj84QkQ4Se2iabiOWjxLVe/Hx8TW7jqnB02cVENHflXQwJAcH2NlVGCibiIiInj9Dyc+zo6Ojg4ODdOx+qr4CWQVE9HcVGor4eCQnw9ISU6bg7l3s3ctaISIiepEOHz587Nixs2fPNm7cePbs2fn5+VUv7SYZ7L8R0d9WYiIGDsS4cXj8GKdPw98fd+6wVoiIiF6kEydODB06dNq0aYWFhQqFYvny5XnSEcaoWrz/jYiIiIiISCfw/jciIiIiIiLdwP4bERERERGRbmD/jYiIiIiISDew/0ZERERERKQb2H8jIiIiIiLSDey/ERERERER6Qb234iIiIiIiHQD+29ERERERES6gf03IiIiIiIi3cD+GxERERERkW5g/42IiIiIiEg3sP9GRERERESkG9h/IyIiIiIi0g3svxEREREREemG/w/nMLuZXxItNQAAAABJRU5ErkJggg==)

**Step 2) Check service status and logs**

Run the following command

```
systemctl status concourse-worker
```

The service status should be in active/running state

![worker-systemd-status](/assets/images/worker-systemd-status-51411a53ace63061f1ee274de364978b.png)

Then look at the worker logs file here `/var/log/concourse-worker.log` or running `journalctl -eu concourse-worker`

For a successful log line such as

```
{"timestamp":"2022-04-08T05:55:25.988837053Z","level":"info","source":"worker","message":"worker.beacon-runner.beacon.rebalance.registered","data":{"session":"4.1.58143"}}
```

However if you have one of the following common errors, refer to the step **3)** to validate your configuration:

```
# Common solution: Scheduler host or port incorrect
{"timestamp":"...","level":"error","source":"worker","message":"worker.beacon-runner.beacon.dial.failed-to-connect-to-any-tsa","data":{"error":"all worker SSH gateways unreachable","session":"4.1.1"}}
{"timestamp":"...","level":"error","source":"worker","message":"worker.beacon-runner.beacon.exited-with-error","data":{"error":"all worker SSH gateways unreachable","session":"4.1"}}

# Common solution: Team id, TSA public key or worker key incorrect
{"timestamp":"...","level":"error","source":"worker","message":"worker.beacon-runner.failed","data":{"error":"failed to establish SSH connection with gateway: ssh: handshake failed: ssh: unable to authenticate, attempted methods [none publickey], no supported methods remain","session":"4"}}
```

**Step 3) Ensure the configuration is correct**

By editing the generated `/var/lib/concourse/concourse-worker` file you can validate with your system administrator if the highlighted lines are correct:

```
#!/bin/bash
...
exec /var/lib/concourse/bin/concourse worker \
  --tsa-host "scheduler.cycloid.io:32223" \
  --tsa-public-key /var/lib/concourse/host_key.pub \
  --tsa-worker-private-key /var/lib/concourse/worker_key \
  --name $(hostname) \
  --work-dir /var/lib/concourse/datas \
   \
  --team 9620fd79-7c8e-414e-9072-8e1604375b98 \
...
```

* `tsa-host` refer to Cycloid scheduler host and port.
* `tsa-public-key` refer to Cycloid scheduler public TSA key
* `tsa-worker-private-key` refer to Cycloid worker key
* `team` refer to Cycloid CI team name

tip

You can retrieve Cycloid CI team name on the console:

1. Click on your top right **profile picture**, and select `Organization settings`

![](/img/org_settings.png)

1. You should find the CI team in the `General` tab, `metadata` section

## known errors[​](#known-errors "Direct link to known errors")

If you have encountered an error message, you can also refer to the following **[section known errors](/reference/ci-cd-pipelines/concepts/workers/known-errors.md)**, which compiles known errors.

## Get help from Cycloid[​](#get-help-from-cycloid "Direct link to Get help from Cycloid")

If your worker is not running correctly, you can create a system report of your worker and share the encrypted result with Cycloid.

The following command will create a Cycloid worker system report and provide a link to share with the Cycloid team:

```
curl -sSL https://raw.githubusercontent.com/cycloidio/cycloid-utils/master/report/worker_report.sh | sudo bash
```

The report contains information like running process, services and network configuration, logs, etc. You can find more details [on Github](https://github.com/cycloidio/cycloid-utils/tree/master/report#worker_reportsh).


---

# Snippets

## How to cleanup old Amazon AMI after a build[​](#how-to-cleanup-old-amazon-ami-after-a-build "Direct link to How to cleanup old Amazon AMI after a build")

Add the following sample on top of your pipeline, in the `shared` section filling the highlighted fields to match your needs.

```
shared:
  - &aws-ami-cleaner
    task: aws-ami-cleaner
    config:
      platform: linux
      image_resource:
        type: registry-image
        source:
          repository: cycloid/cycloid-toolkit
          tag: latest
      run:
        path: /usr/bin/aws-ami-cleaner
      params:
        AWS_ACCESS_KEY_ID: ((aws_access_key))
        AWS_SECRET_ACCESS_KEY: ((aws_secret_key))
        AWS_NAME_PATTERNS: >
                  [
                    "project1_front_prod",
                    "project1_batch_prod"
                  ]
```

Then create a dedicated job to call this new tasks or simply call it in your existing job after the build of the Amazon AMI :

```
- name: clean-worker-ami
  plan:
  - do:
    - get: ((project))-worker-build-ami
      passed:
        - deploy-((project))-((env))
      trigger: true

    - *aws-ami-cleaner
```

## How to cleanup old container images from Amazon ECR[​](#how-to-cleanup-old-container-images-from-amazon-ecr "Direct link to How to cleanup old container images from Amazon ECR")

Add the following sample on top of your pipeline, in the `shared` section filling the highlighted fields to match your needs.

```
shared:
  - &aws-ecr-cleaner
    task: aws-ecr-cleaner
    config:
      platform: linux
      image_resource:
        type: registry-image
        source:
          repository: cycloid/cycloid-toolkit
          tag: latest
      run:
        path: /usr/bin/aws-ecr-cleaner
      params:
        AWS_ACCESS_KEY_ID: ((aws_access_key))
        AWS_SECRET_ACCESS_KEY: ((aws_secret_key))
        REGION: ((aws_default_region))
        DRYRUN: False
        IMAGES_TO_KEEP: 2
        REPOSITORIES_FILTER: 'foo bar'
        # For a global clean with exclude:
        IGNORE_TAGS_REGEX: 'dev|staging|prod|latest-'
        # For a clean on specific tag/env
        FILTER_TAGS_REGEX: '^dev-'
```

Then create a dedicated job to call this new tasks or simply call it in your existing job after the push of container image :

```
- name: clean-worker-ami
  plan:
  - *aws-ecr-cleaner
```


---

# Common errors / troubleshooting

## Common pipeline errors[​](#common-pipeline-errors "Direct link to Common pipeline errors")

### Job/task : invalid tag format[​](#jobtask--invalid-tag-format "Direct link to Job/task : invalid tag format")

Error message :

Error

```
resource script '/opt/resource/check []' failed: exit status 1

stderr:
failed to construct tagged reference: invalid tag format
```

This error usually occurs because of a typo in the docker image name which contain also the tag :

```
      - task: foo
        config:
          image_resource:
            source:
              repository: docker:dind
```

Solution

Use the expected `tag` field in pipeline configuration to provide a specific docker image.

```
            source:
              repository: docker
              tag: dind
```

### Job/task : 401 Unauthorized[​](#jobtask--401-unauthorized "Direct link to Job/task : 401 Unauthorized")

Error

```
resource script '/opt/resource/check []' failed: exit status 1

stderr:
failed to fetch digest: 401 Unauthorized
```

This error usually occurs because the docker image specified does not exist on dockerhub :

```
            source:
              repository: docker/foobar
```

Solution

Ensure the image specified is a valid one using `docker pull docker/foobar`

### Resource/Job : Expected to find variables[​](#resourcejob--expected-to-find-variables "Direct link to Resource/Job : Expected to find variables")

Error

```
Checking failed

Expected to find variables: ssh_access
```

Which mean the pipeline is looking for a variable or a credential which is not configured.

It could come from a missing variable defined into your pipeline and not in the `variables.sample.yaml`. Or most of the time it come from a missing credential required by the pipeline. See more about [credentials here](/reference/credentials/.md). And how configure and use it into a [pipeline here](/reference/stackforms/concepts/technologies.md#pipeline). This error usually occurs because the docker image specified does not exist on dockerhub :

```
  - name: git_master
    type: git
    source:
      private_key: ((ssh_access.ssh_key))
```

Solution

In this case the solution was to create a new Cycloid credential named `access` of type `ssh` in our organization.

### Pipeline logs not displayed[​](#pipeline-logs-not-displayed "Direct link to Pipeline logs not displayed")

An issue has been identified where pipeline logs are not displayed. Or not fully displayed. The pipelines logs are get through an api call called `/events` of type event-stream.

If your pipeline don't display logs the issue usually could come from a proxy server not allowing this type of traffic. We also saw this behavior with Netscaler and [HTTP compression](https://docs.netscaler.com/en-us/citrix-adc/current-release/optimization/http-compression.html) configuration.

## Troubleshooting[​](#troubleshooting "Direct link to Troubleshooting")

### Connect in a pipeline running container[​](#connect-in-a-pipeline-running-container "Direct link to Connect in a pipeline running container")

> A build is an execution of a build plan, which is either configured as a sequence of steps in a job, or submitted directly to Concourse as a one-off build via fly execute.
>
> Containers and volumes are created as get steps, put steps, and task steps run. When a build completes successfully, these containers go away.
>
> A failed build's containers and volumes are kept around so that you can debug the build via fly intercept. If the build belongs to a job, the containers will go away when the next build starts. If the build is a one-off, its containers will be removed immediately, so make sure you intercept while it's running if you want to debug.

<https://concourse-ci.org/builds.html#fly-intercept>

To use `fly intercept` in Cycloid start to get the required information:

Note

To get `CY_ORG_TEAM`, click on the **name of your Organization** within the left menu ![](/img/manage_org.png) and copy the `ci_team_member` value.

```
export CY_ORG_TEAM=
export CY_PROJECT=
export CY_ENV=
export CY_COMPONENT=
export CY_PIPELINE_JOB=

# Specify the Concourse URL
# For onprem setup
export CONCOURSE_URL=http://<Onprem address>:8080
# For SaaS users
export CONCOURSE_URL=https://scheduler.cycloid.io
```

Then simply connect on the running container using fly cli:

```
# Get Concourse fly cli
curl -JO "$CONCOURSE_URL/api/v1/cli?arch=amd64&platform=linux"
chmod +x fly

# Login and connect on the running container
fly --target $CY_ORG_TEAM login -n $CY_ORG_TEAM --concourse-url "$CONCOURSE_URL" -k -u admin -p admin
fly --target $CY_ORG_TEAM  intercept -j "${CY_PROJECT}-${CY_ENV}-${CY_COMPONENT}/$CY_PIPELINE_JOB" sh
```

### Manually re-trigger a pipeline build[​](#manually-re-trigger-a-pipeline-build "Direct link to Manually re-trigger a pipeline build")

There are case when a pipeline fails for temporary reasons or causes external to the environment you have under control. In such cases it is possible to manually re-trigger the pipeline once the external or transitory issues are solved.

Briefly the steps needed are:

1. Pin the resource version
2. Re-trigger the pipeline
3. Unpin the resource version once the pipeline started

In more details to pin a resource version you have to click on the resource in the pipeline visualization page. For example in the picture below you can click on the `git_stack-ansible` box to access the history of version of that resource.

![Pipeline](data:image/png;base64,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)

Clicking on the resource brings you a list of versions for the selected resource, see picture below.

![Resource version](/assets/images/resource-version-46087d9708fcf9dc69ab3c7658a5a528.png)

In this view each line represents a version of the resource. And in each line there is a 'pin' icon, clicking on the icon pins the resource version, a pinned version will be used for the next executions of the pipeline.

The figure below shows a pinned resource version.

![Pinned version](/assets/images/pinned-resource-version-2e80ba9ea7d4ac7d536a05b579bc6914.png)

Going back to the pipeline view, we can notice that the pinned resource is highlighted in purple, as shown in the figure below.

![Pinned version pipeline](data:image/png;base64,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)

All that is left now is to manually trigger the job as explained as before in this section, clicking on the green box representing the job getting the pinned resource and then on the "+" icon.

Beware that all the next executions of a job will use the pinned version of a resource until it stays pinned. It is advisable to unpin it after the job starts.


---

# Pipeline style guide

### Reduce log outputs[​](#reduce-log-outputs "Direct link to Reduce log outputs")

Some standard commands used in pipelines generate a lot of output lines or progress bars. Which makes the whole build log output sometimes hard to read. To reduce this output, this is our tips for common commands :

#### Apk[​](#apk "Direct link to Apk")

```
apk add -q --no-progress ...
```

#### Curl/wget[​](#curlwget "Direct link to Curl/wget")

```
curl -s ...
wget -q ...
```

#### Pip[​](#pip "Direct link to Pip")

```
pip -q install ...
```

#### Easy\_install[​](#easy_install "Direct link to Easy_install")

```
easy_install --quiet ...
```

#### APT[​](#apt "Direct link to APT")

```
apt-get update -qq > /dev/null
apt-get install -yqq ... > /dev/null
```

#### Npm[​](#npm "Direct link to Npm")

```
npm install --silent
npm build --silent ...
yarn install --silent
```

#### Php-composer[​](#php-composer "Direct link to Php-composer")

```
composer -q ...
php composer.phar install -q
```

#### Ansible / Packer-ansible[​](#ansible--packer-ansible "Direct link to Ansible / Packer-ansible")

Make sure all ansible command are prefixed or have this env var `ANSIBLE_STDOUT_CALLBACK=actionable` to use [callback/actionable - shows only items that need attention](https://docs.ansible.com/ansible/2.9/plugins/callback/actionable.html)

Same case for Packer, make sure all shell commands also respect the points above (apt, ...)

Eg the `packer.json` for the ansible call

```
{
    ...
    "type": "ansible-local",
    "command": "ANSIBLE_STDOUT_CALLBACK=actionable ANSIBLE_FORCE_COLOR=1 PYTHONUNBUFFERED=1 ansible-playbook",
    ...
}
```

### Use bash trap in scripts[​](#use-bash-trap-in-scripts "Direct link to Use bash trap in scripts")

One of the pattern is to kill a process faster, when a job succeeds or fails and control better the log output. So that you can display a simple "OK" when everything went fine, or the full logs when it failed.

This is a dummy example that you can put at the beginning of a script in a task, which illustrates a way to implement it:

```
path: /bin/bash
args:
- -ec
- |
  function finish {
      if [ $rc != 0 ]; then
        echo "Build finished with error, displaying the verbose log file ..."
        cat verbose_log_file
      fi
  }
  trap 'rc=$?; set +e; finish' EXIT

  ... doing some stuff ...

  make test > verbose_log_file
```

### Define global and default variables to tasks[​](#define-global-and-default-variables-to-tasks "Direct link to Define global and default variables to tasks")

As you might have already learned in our [create my first private stack](/cookbook/getting-started/devops-teams/stack-creation/.md) guide, we can use [YAML Alias indicators](https://yaml.org/spec/1.2/spec.html#id2786196) to reduce the size of pipeline templates.

The code below uses the` params` field in the `task` and `config` sections of the pipeline template to provide local and global variables.

```
shared:
  - &task-template
    config:
      platform: linux
      image_resource:
        type: registry-image
        source:
          repository: busybox
      params:
        GLOBAL_MESSAGE: Common message to all tasks
      run:
        path: /bin/sh
        args:
          - '-ec'
          - |
            echo "Global message: ${GLOBAL_MESSAGE}"

            echo "Local message: ${LOCAL_MESSAGE}"

            echo "Default message ${LOCAL_MESSAGE:-$GLOBAL_MESSAGE}"

jobs:
  - name: job-hello-world
    build_logs_to_retain: 3
    plan:
      - task: foo
        <<: *task-template
        params:
          LOCAL_MESSAGE: Here is a local message from foo
      - task: bar
        <<: *task-template
        params:
          LOCAL_MESSAGE: Here is a local message from bar
      - task: bli
        <<: *task-template
```

This is a good example of how to share the code across several `tasks` and be able to specify custom `params` for each of them. As shown on **Line 20**, by using some [**bash's parameter substitution** syntax](https://tldp.org/LDP/abs/html/parameter-substitution.html), we can use an optional `params` local variable given by a task as a way to override the default global value.


---

# Cycloid CLI

## Introduction[​](#introduction "Direct link to Introduction")

If you are a user of Cycloid and want to push automation a little bit further by playing with our Cycloid API, the Cycloid CLI is here for you.

Here at Cycloid, our DevOps team is using it almost every day to perform routine tasks, technical demonstrations for new customers, or even to send events to the Cycloid console.

The Cycloid CLI is one of our Open Source projects. If you want to contribute to it, you can check out the code on our [Github repository](https://github.com/cycloidio/cycloid-cli).

## Installation[​](#installation "Direct link to Installation")

Details

Requirements

Supported OS/Platform:

* GNU/Linux amd6
* MacOs amd64/arm64
* Windows amd64

Precompiled binaries for released versions are available in the [release page](https://github.com/cycloidio/cycloid-cli/releases/latest) on Github. Using the latest production release binary is the recommended way of installing the Cycloid CLI.

tip

Here is a oneliner to download and make it executable under `/usr/local/bin` using `bash`, `curl`, `sudo` and `jq`:

```
export os="$(uname -s | tr [:upper:] [:lower:])"; \
if [[ "$(uname -m)" == "x86_64" ]]; then export platform=amd64 ; else export platform=arm64 ; fi; \
  curl -sLO $(curl -s https://api.github.com/repos/cycloidio/cycloid-cli/releases/latest | jq -r '.assets[] | select(.name=="cy") | .browser_download_url') \
    && chmod +x cy \
    && sudo mkdir -p /usr/local/bin \
    && sudo mv cy /usr/local/bin
```

### Setup completion[​](#setup-completion "Direct link to Setup completion")

Completion is available for bash, fish, zsh and powershell.

Add the required line to your `.bashrc` or `.zshrc` file.

.bashrc

```
# bash
source <(cy completion bash)
```

.zshrc

```
# zsh
source <(cy completion zsh)
```

For fish, write the file here

```
# fish
cy completion fish > ~/.config/fish/completions/cy.fish
```

And for powershell, append the completion content in the `$PROFILE`

```
Add-Content $PROFILE "if (Get-Command cy -ErrorAction SilentlyContinue) {
  cy completion powershell | Out-String | Invoke-Expression
}"
```

## Quickstart[​](#quickstart "Direct link to Quickstart")

### Authentification[​](#authentification "Direct link to Authentification")

Cycloid CLI uses [Cycloid API Keys](/reference/api/.md) to authenticate with at least `organization::read` authorization.

tip

You can generate an API key [in the Security->API Keys section on the console](https://console.cycloid.io/).

Two login methods are available:

* Env var
* Login

You can set the `CY_API_KEY` environment variable and every command will use it.

### Usage in pipeline[​](#usage-in-pipeline "Direct link to Usage in pipeline")

```
jobs:
- name: "use cy cli"
  plan:
  - do:
    - task: "use cy cli"
      config:
        platform: "linux"
      image_resource:
        type: registry-image
        source:
          repository: cycloid/cycloid-tookit
          tag: latest
      params:
        CY_API_KEY: ((your_api_key_credential))
      run:
        path: "/bin/bash"
        args:
        - -exc
        - |
          # Use any cycloid command here
```

warning

Try to use the environment variable as much as possible.

This behavior will be deprecated.

A `cy login` will write your API key in your `$HOME/.cycloid` folder.

To login to Cycloid with the CLI run:

```
cy login --org <your_org> --api-key <your_api_key>
```

warning

Use an environment variable to avoid putting your API key in your command line history.

You can login to as many orgs as you like, each org will be scoped by the `cy --org` flag.

### Usage in pipeline[​](#usage-in-pipeline-1 "Direct link to Usage in pipeline")

warning

In a pipeline, it is recommended to use the environment variable.

Inside a Cycloid pipeline, you can use cycloid credentials to pass the API key.

```
jobs:
- name: "use cy cli"
  plan:
  - do:
    - task: "use cy cli"
      config:
        platform: "linux"
      image_resource:
        type: registry-image
        source:
          repository: cycloid/cycloid-tookit
          tag: latest
      run:
        path: "/bin/bash"
        args:
        - -exc
        - |
          cy --org ($ organization_canonical $) login --api-key ((your_api_key_credential))
```

## Environment variables[​](#environment-variables "Direct link to Environment variables")

You can use the following environment variables to configure your CLI:

| name          | description                                                                                                                                                                  |
| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| CY\_API\_URL  | Specify the HTTP url of Cycloid API to use, default <https://http-api.cycloid.io>, you can use the special variable ($ .api\_url $) to point to the current console API URL. |
| CY\_ORG       | Set the current organization (will be overrident by the `--org` flag)                                                                                                        |
| CY\_PROJECT   | Set the current project (will be overrident by the `--project` flag)                                                                                                         |
| CY\_ENV       | Set the current environment (will be overrident by the `--env` flag)                                                                                                         |
| CY\_COMPONENT | Set the current component (will be overrident by the `--component` flag)                                                                                                     |
| CY\_API\_KEY  | Set the current API key                                                                                                                                                      |
| CY\_VERBOSITY | Set the verbosity level (debug, info, warning, error), default warning                                                                                                       |

## Command list[​](#command-list "Direct link to Command list")

```
Usage:
  cy [command]

Available Commands:
  api-key            Manage organization API keys
  beta               Experimental commands.
  catalog-repository Manage the catalog repositories
  completion         Output shell completion for the given shell (bash or zsh)
  components         Manage components.
  config-repository  Manage the catalog repositories
  credential         Manage the credentials
  environment        Manage the environments of a project.
  event              Manage the events
  external-backend   manage external backends
  help               Help about any command
  infrapolicy        Manage the infraPolicies
  kpi                Manage the kpis
  login              Login against the Cycloid console
  members            Manage members from the organization
  organization       Manage the organizations
  pipeline           Manage the pipelines
  project            Manage the projects
  roles              Manage roles from the organization
  stack              Manage the stacks
  status             Get the status of the Cycloid services
  terracost          Use terracost feature
  version            Get the version of the consumed API

Flags:
      --api-url string     Specify the HTTP url of Cycloid API to use eg https://http-api.cycloid.io. This can also be given by CY_API_URL environment variable. (default "https://http-api.cycloid.io")
  -h, --help               help for cy
      --insecure           Decide to skip or not TLS verification
      --org string         Specify the org to use. override CY_ORG env var. Required for all Org scoped endpoint.
  -o, --output string      The formatting style for command output: json|yaml|table (default "table")
  -v, --verbosity string   Override the default verbosity for this command. VERBOSITY must be one of: debug, info, warning, error, critical, none. (default "warning")
      --version            version for cy

Use "cy [command] --help" for more information about a command.
```


---

# Cycloid URI References

The Cycloid CLI can resolve Cycloid URI references to either fetch or interpolate in files Cycloid data like Credentials, Inventory values, Terraform outputs or anything that can be fetched from the Cycloid API.

An URI resource path is defined like this:

```
cy://<api_path>[?<param>=<value>&<param2>=<value>...]
```

Where:

* `api_path`

  * Any valid path from our API as defined in our [API docs](/api/)

* `params`

  * Urlencoded parameters, they can be either an API parameter, or a formatting parameter. formatting parameters allow you to define how the CLI must format the API payload.

    By default the output will be JSON for objects and array and a string for any simple value.

* `value`

  * The value of the parameter, some don't require any value.

<!-- -->

Examples

* Fetch a SSH Key named `my-ssh-key` in org `my-org`:

- URI
- output

```
cy://organizations/my-org/credentials/my-ssh-key?key=.raw.ssh_key
```

Output an ssh key

```
--- BEGIN OPENSSH PRIVATE KEY ---
jzdhlkajzhdklazhdklajzhdkjahzdkjahz
azjkdhalzkjdhaklzdhakljzhdklajzhdkl
...
--- END OPENSSH PRIVATE KEY ---
```

* Fetch a component data an display it as yaml:

- URI
- output

> Note, you can use [shortcuts](#shortcuts) like org instead of organizations

```
cy://org/my-org/projects/my-project/environments/my-env/components/my-ssh-component?output=yaml
```

Output an ssh key

```
id: 2480
name: StackForms array testing
canonical: stackforms-array-testing
cloudprovider: null
createdat: 1747902212000
description: ""
environment:
    canonical: staging
    color: dev
    components: []
    createdat: 1745844022000
    id: 14954
    name: staging
    updatedat: 1745844022000
importstatus: ""
project:
    canonical: fbh-playground
    color: dev
    createdat: 1744203147000
    description: ""
    favorite: false
    icon: folder_open
    id: 6557
    name: FBH Playground
    owner: null
    updatedat: 1747339980000
updatedat: 1758709009000
usecase: default
```

### Parameters:[​](#parameters "Direct link to Parameters:")

#### `key`[​](#key "Direct link to key")

Query the output value using gojq syntax ( <https://github.com/itchyny/gojq> ) that match jq syntax, see the manual here <https://jqlang.org/manual>

The basic syntax is starting with a `.` that represent the current object. You can access keys by their names `.<key>` and use array syntax for lists `.[]`

If no key is provided, the output will be the basic API Response. You can check API responses on our [API documentation](/api/)

#### `output`[​](#output "Direct link to output")

To specify the output format only the key is required. e.g. `cy://path?output=yaml` will output in yaml each format key can be paired with options as values e.g. `cy://path?output=yaml&indent_size=4` set the indent to 4 here is all the format and their options

* `json` (default) Format the API output in JSON.

* `yaml` Format the API output in YAML.

No matter which output format, any simple value (string, number, bool) will be output as is.

note

The yaml formatter will add an extra newline on simple values.

###### Output related parameters[​](#output-related-parameters "Direct link to Output related parameters")

* `json_compact` (only for json output)

  * Will output a compact json on one line like `{"hello":"world"}`

* `json_escape` (only for json output)

  * Will escape the output json like `"{\"hello\":\"world\"}"`

* `indent_size=<int>`

  * Set the indentation level for the output (for YAML or JSON)

### Transformers parameters[​](#transformers-parameters "Direct link to Transformers parameters")

Transformers allows you to add additional string transformations to the formatted output.

* `indent=int`

  * indent the output text by `int` from the left

* `nindent=int`

  * same as indent but start with a newline

* `base64<=bool>`

  * encode the output as base64

### Shortcuts[​](#shortcuts "Direct link to Shortcuts")

You can shorten some resources names in the URI pattern for brevity, here is a list:

* `org`, `organization` -> `organizations`
* `project` -> `projects`
* `env`, `environment` -> `environments`
* `component` -> `components`
* `cred`, `credential` -> `credentials`

## Usage[​](#usage "Direct link to Usage")

To retrieve or inject the values, check out the `cy uri --help` command.

### `cy uri get` or `cy get`[​](#cy-uri-get-or-cy-get "Direct link to cy-uri-get-or-cy-get")

This command allows you to fetch any resource and output it on the terminal.

This allows you to test an uri reference, and also get any resource in the API that is not yet implemented on simple commands.

#### Usage[​](#usage-1 "Direct link to Usage")

```
Get a cycloid resource by its URI Path.

Usage:
  cy get [uri] [flags]

Examples:
Fetch a credential by its canonical as JSON
  cy get cy://organizations/my-org/credentials/my-cred?output=json

Fetch an ssh_key
  cy get cy://organizations/my-org/credentials/my-ssh?key=.raw.ssh_key
```

### `cy uri interpolate`[​](#cy-uri-interpolate "Direct link to cy-uri-interpolate")

This command allows you to interpolate Cycloid URI references in files.

You can do it in three manners:

1. Interpolate value in files in-place (replacing the content of the files)

```
$ cy uri interpolate --in-place [files...]
```

2. Output interpolated files to a destination folder

```
$ cy uri interpolate --directory target_dir/ [files...]
```

info

Relative file path will be replicated in the target dir like so

```
./relative/dir/file.yml -> target_dir/relative/dir/file.yml
```

But all files coming from absolute path will be redendered at the target dir's root:

```
/home/bruno/config -> target_dir/config
```

Note also that you can't use the `-(-d)irectory` and `-(-i)n-place` flags together.

3. Output interpolated files to stdout

```
$ cy uri interpolate [files...]
```

### Recursive and ignore files[​](#recursive-and-ignore-files "Direct link to Recursive and ignore files")

You can use the `-(-r)ecurse` flag to recursively interpolate all files contained in a directory and its child.

```
$ cy uri interpolate --recursive .
```

To ajust the `-(-r)ecurse` blast radius and skip unwanted files, you can use the `--ignore` flag multiple times to specify patterns to ignore during interpolation.

This flags accepts [go regex](https://github.com/google/re2/wiki/Syntax) patterns:

Here is an example that ignores `.git` folders and `.sql` files

```
cy uri interpolate --directory . --ignore .git --ignore "*.sql"
```


---

# Examples

## Create an component using stackforms[​](#create-an-component-using-stackforms "Direct link to Create an component using stackforms")

This command is very useful to automate components.

The variables must be in JSON format with the following format:

```
{
  "section name": {
    "group name": {
      "variable_key": <value>
    }
  }
}
```

You can also use the helpful `--var (-V)` to fill them in a console friendly manner:

```
-V "section name.group name.var_key=<value>"
```

tip

Some string values can be ambiguous like "3642", those could be counted as int in the parsing of your variable.

You can force a string value by quoting it in the string:

```
-V "section name.group name.var_key="<explicit string value>""
```

```
cy component create --org myOrg \
  -p myProject -e myNewEnv \
  -s stack:ref \
  -u stack-usecase \
  --json-file path/to/vars.json \
  --json-vars '{"section": {"group": {"myVar": "foo" }}}' \
  --var section.group.var=value
```

tip

You can also specify variables using the env var `CY_STACKFORM_VARS` as a JSON string too.

note

The CLI will fill the value not specified by the user by using the default of the stacks.

If a required variable is not filled, you will get an error.

You can also make the creation idempotent by adding the `--update` flag.

This is useful to push value on a component that could not be already created.

## Validate stackforms[​](#validate-stackforms "Direct link to Validate stackforms")

The Cycloid CLI can be used to validate stackforms files.

This is very useful for stack creators, it is a more convenient way to check the validity of your stack.

```
cy stack forms validate .forms.yml
```

## Output result in JSON[​](#output-result-in-json "Direct link to Output result in JSON")

Use the `--output json` flag to output the result in JSON format.

```
cy project list -o json | jq -r .
```

## Credentials management[​](#credentials-management "Direct link to Credentials management")

Lookup the [manage credentials using the CLI](/reference/credentials/examples/using-the-cli.md) section.

## Create a catalog repository[​](#create-a-catalog-repository "Direct link to Create a catalog repository")

note

You will need to provide a valid SSH credential canonical for the git repo you want to use.

```
cy --org <your_org> catalog-repository create \
	--branch <catalog_branc> --cred <git_ssh_credential> \
	--url <you_git_catalog_repo> --name "my_catalog_repo"
```

## Delete a catalog repository[​](#delete-a-catalog-repository "Direct link to Delete a catalog repository")

warning

All project using a stack inside the repository must be deleted before the repository can be deleted.

```
cy --org <your_org> catalog-repository delete --canonical <catalog_repo_canonical>
```

## Create a config repository[​](#create-a-config-repository "Direct link to Create a config repository")

note

You will need to provide a valid SSH credential canonical for the git repo you want to use.

```
cy --org <your_org> catalog-repository create \
	--branch <catalog_branc> --cred <git_ssh_credential> \
	--url <you_git_catalog_repo> --name "my_config_repo" \
  --default # Add the default flag if you want to set this repository as default config repository for the current org
```

## Read component config (require stack using stackforms)[​](#read-component-config-require-stack-using-stackforms "Direct link to Read component config (require stack using stackforms)")

This command allows you to fetch the current config of a component using stackforms.

```
$ cy --org myOrg component config get -p project -e env -c component
{
  "section": {
    "group": {
      "var": "foo"
    }
  }
}
```

The output format matches the input format for `cy component create`, allowing you to easily duplicate an environment by piping the output.

```
$ cy --org myOrg project get-env myProject env1 \
  | cy --org myOrg \
    -p myProject -e myNewEnv \
    -u stack-usecase \
    --json-file - \
    -V section.group.var_to_override=<new_value>
```

## List all pipelines not triggered since 60 days and pause them[​](#list-all-pipelines-not-triggered-since-60-days-and-pause-them "Direct link to List all pipelines not triggered since 60 days and pause them")

tip

This script is excellent to reduce the load on your concourse workers.

```
export CY_ORG=cycloid-sandbox

cy pipelines last-used --since-days 60 -o json |
  jq -c '{project: .[].Project, env: .[].Environment}' |
  while read -r json; do
    project=$(echo "$json" | jq -r .project)
    env=$(echo "$json" | jq -r .env)

    cy pipelines pause --project "$project" --env "$env"
  done
```


---

# Cloud carbon footprint

This feature allows you to check your carbon footprint from your cloud usage.

It's embedded within our [Cloud Cost Management](/reference/cloud-cost-management/.md "Cloud Cost Management") and our cost-estimation tools and displays factual carbon footprint data alongside your cloud costs.

You can visualize your data with different granularities as you would for the cloud costs but also in terms of real-world equivalents, e.g comparaison of cloud footprint to a flight trip carbon emission.

Here's a quick video presentation about it.

[YouTube video player](https://www.youtube.com/embed/NtX4c5CvetQ?si=kocKCwPBQOfPaFFN)

### How is the cloud carbon footprint calculated?[​](#how-is-the-cloud-carbon-footprint-calculated "Direct link to How is the cloud carbon footprint calculated?")

If you would wish to know more about how the carbon footprint is calculated using Cloud Carbon Footprint, you can consult the public documentation of the opensource project that this feature is based on available [here](https://www.cloudcarbonfootprint.org/docs/methodology/).

## Quickstart[​](#quickstart "Direct link to Quickstart")

Cloud Carbon Footprint is the only non-optional Cycloid feature.

We have a strong stance on environmental issues and believe that everyone should make better planet-friendly decisions <!-- -->🌱

For that reason, you cannot choose to opt-out of carbon footprint data when using the Cloud Cost Management (CCM) the feature where it’s embedded.

Check the CCM [quickstart](/reference/cloud-cost-management/.md#quickstart "CCM Quickstart") documentation to learn how to to start using Cloud Carbon Footprint.


---

# Cloud Cost Management

<!-- -->

<!-- -->

## Introduction[​](#introduction "Direct link to Introduction")

Cloud Cost Management (CCM) is a feature that enables you to analyze in detail the costs generated by your cloud infrastructure.

It offers an intuitive graphical interface that helps anyone within your organization visualize, manage, and explore cloud expenses across multiple providers with ease.

![](/img/ccm/ccm-dashboard.png)

<br />

In a nutshell, this tool begins by retrieving data from your cloud providers, allowing you to visualize and analyze it through an intuitive dashboard.

In the following sections, you'll learn how to get started with Cloud Cost Management and explore all of its key features.

note

Within this feature, our [Cloud Carbon Footprint](/reference/cloud-carbon-footprint/.md "Cloud Carbon Footprint") tool is integrated, allowing you to visualize your cloud carbon footprint data alongside your cost data. Because of this integration, it is not possible to opt out of carbon footprint data when using CCM.

## Pre-requisites[​](#pre-requisites "Direct link to Pre-requisites")

In order to use this feature you need to have the rigth access keys to be able to connect to the cloud provider and extract the data required.

This access keys will be stored as a cycloid credential to allow the Cloud Cost Management (CCM) account to access the cloud provider data. For more informations regarding credentials, please refer to the corresponding section [here](/reference/credentials/.md "Credentials").

As of now there's 3 cloud providers that are supported in CCM, that is AWS, GCP and Azure. New ones can be integrated if needed, don't hesitate to reach out to us if this is your case.

In the following table you have a summary of the providers supported, the data retrieved and instructions on how to configure the cloud access keys for CCM.

* ![AWS](/img/ccm/aws-logo.png)
* ![Azure](/img/ccm/azure-logo.png)
* ![GCP](/img/ccm/gcp-logo.png)

CCM with AWS is based on the [aws cost and usage report (CUR)](https://docs.aws.amazon.com/cur/latest/userguide/what-is-cur.html "AWS Cost and Usage Report (CUR)"). It uses the generated reports to retrieve the data about your cloud consumption.

To use CCM using AWS there's only 2 things that you will need to prepare:

* Setup cost and usage report (CUR)
* Create an AWS Access key with the rigth permissions

#### 1. Setup cost and usage report (CUR)[​](#1-setup-cost-and-usage-report-cur "Direct link to 1. Setup cost and usage report (CUR)")

The AWS CUR contains the most complete set of your AWS costs and data publishes. It works by publishing a AWS billing reports to an Amazon Simple Storage Service (Amazon S3) bucket that you own.

note

The old depracted version [aws-detailed-billing-report](https://docs.aws.amazon.com/cur/latest/userguide/detailed-billing.html "AWS Detailed Billing Reports (DBR)") is also supported by CCM.

To use CCM you first need an initial AWS billing report, from which the CCM will retrieve the data of your cloud costs.

You can follow AWS official tutorial acessible [here](https://docs.aws.amazon.com/cur/latest/userguide/cur-create.html).

note

Access to the billing console is restricted by default on AWS and needs to be [granted by an administrator](https://docs.aws.amazon.com/awsaccountbilling/latest/aboutv2/control-access-billing.html#grantaccess). In case of issues, the troubleshooting guide is [here](https://aws.amazon.com/premiumsupport/knowledge-center/iam-billing-access/).

Here are the configurations to choose while following the AWS tutorial:

* In the first step select the options `Include resource IDs` and `Automatically refresh your Cost & Usage Report when charges are detected for previous months with closed bills`
* Concerning `time granularity` do not select Monthly as this will severely restrict the capabilities of CCM. Use instead `Hourly` or `Daily`
* No need to `Enable report data integration for` any other system, CCM only needs the files generated by the CUR
* All `Compression types` are supported, you can leave the default one or chose a different one

After the S3 bucket and report are created, keep in mind the `bucket name`, its `region`, as well as the location of the `manifest file` within the bucket. This will be required during the setup of the CCM account.

#### 2. Create AWS Access key[​](#2-create-aws-access-key "Direct link to 2. Create AWS Access key")

As you will see, the procedure to create a Cloud Cost Management account starts by selecting or creating a cycloid credential containing the access keys, in this case for AWS.

This access key needs to have access to the S3 bucket where the reports will be stored, as it was configured before.

To do this you'll need to create an `IAM user` with an `access key` and attach an `IAM permission policy` to it, to enable certain rigths for this user.

note

As of now CCM doens't support AWS IAM roles, so you'll need to create a user and access keys with permissions as we saw above.

Creating the IAM user should be quite straigthforward, you can follow the AWS official tutorial on how to do in the AWS console available [here](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_create.html).

Tips when creating the user:

* `Don't select the option to Provide user access to the AWS Management Console`, since the user will be a machine user that will not require login in aws console.

* Associate the `IAM permission AmazonS3ReadOnlyAccess` to the user directly. Optionally if you want to have minimal permissions possible you can create an IAM policy with the following permission

  <!-- -->

  ```
  {
  	"Version": "2012-10-17",
  	"Statement": [
  		{
  			"Sid": "VisualEditor0",
  			"Effect": "Allow",
  			"Action": [
  				"s3:GetObject",
  				"s3:ListBucket",
  				"s3:GetBucketLocation"
  			],
  			"Resource": [
  				"arn:aws:s3:::<YOUR_BUCKET_HERE>",
  				"arn:aws:s3:::<YOUR_BUCKET_HERE>/*"
  			]
  		}
  	]
  }
  ```

After creating the user you should create the access key to be used, you can do this by following the AWS official tutorial [here](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html#:~:text=To%20create%2C%20modify%2C%20or%20delete%20the%20access%20keys%20of%20another%20IAM%20user%20\(console\)).

Don't forget to save the `access key` somewhere, since you'll have to add it to a cycloid credential later.

CCM with Azure is based on the [Microsoft Azure Cost Management](https://learn.microsoft.com/en-us/azure/cost-management-billing/costs/overview-cost-management "Azure Cost Management"). It uses the data exports to allow to integrate your cloud costs into CCM.

To use CCM using Azure there's only 2 things that you will need to prepare:

* Verify Azure storage account
* Create an Azure Cost Management export

#### 1. Verify Azure storage account[​](#1-verify-azure-storage-account "Direct link to 1. Verify Azure storage account")

As you will see, the procedure to create a Cloud Cost Management account starts by selecting or creating a cycloid credential containing the access keys, in this case for Azure.

This corresponds to the access key of your storage account. It will be used to connect to your azure account from cycloid.

In case you still don't have one created, you can consult the official documentation about how to create one [here](https://learn.microsoft.com/en-us/azure/storage/common/storage-account-create?tabs=azure-portal).

Don't forget to save the access key and storage account name, since you'll have to add it to a cycloid credential later.

note

If you rather you can also create the storage account simultaneasly to when you create the Azure Cost Management export

#### 2. Create an Azure Cost Management export[​](#2-create-an-azure-cost-management-export "Direct link to 2. Create an Azure Cost Management export")

To be able to do this you need to make sure that your Azure user, or the one you will use to create the Azure Cost Management export, has the required permissions.

You can quickly check this by checking your user role in the Azure resource group associated to the storage account mentioned in the previous section. You can find the azure official tutorial on how to this [here](https://learn.microsoft.com/en-us/azure/role-based-access-control/check-access).

Some of the acceptable roles are: `Owner`, `Contributor` or `Cost Management Contributor`. If you have another role just make sure that it has the permissions to create and update exports of Cost Management.

Once you have verified the roles associated to the user you can create the Azure Cost Management export in the azure portal, by following the steps bellow:

1. Go to the `Cost Management + Billing` from the portal menu
2. Then select the `Cost Management` tab on the left
3. On the Menu on the left, navigate to the `settings` section and click on `Exports`
4. Now you just need to create the export by clicking on the `+ Create` button. Doing this should be quite forward, pay only attention to the following options:

* Select for the parameter `Frequency` the option `Daily exports of month-to-date costs`
* Select the storage account create before or opt for creating a new one
* Choose the `Format` as `CSV` /\*
* Choose the `Compression type` as `None`, Gzip for CSV file format \*/

In case of any issue you can find the complete official guide [here](https://learn.microsoft.com/en-us/azure/cost-management-billing/costs/tutorial-export-acm-data?tabs=azure-portal).

Once you finishing up creating the export, remember that it takes a few hours for the export file to be ready in the storage account's container.

Don't forget to save the `export name` and also the container `name` somewhere, since you'll have to add it to a CCM account later.

CCM with GCP is based on the [Google Cloud billing data exports](https://cloud.google.com/billing/docs/how-to/export-data-bigquery). It uses the generated exports to BigQuery to retrieve your billing data of GCP

To use CCM using GCP there's only 2 things that you will need to prepare:

* Create a service account
* Setup cloud billing data export to BigQuery

#### 1. Create a service account[​](#1-create-a-service-account "Direct link to 1. Create a service account")

As you will see, the procedure to create a Cloud Cost Management account starts by selecting or creating a cycloid credential containing the access keys, in this case for GCP.

This corresponds to the service account key to be used by CCM. It will be used to connect to your GCP account from cycloid.

You can consult the official GCP documentation about how to create a service account [here](https://cloud.google.com/iam/docs/service-accounts-create).

Feel free to follow the tutorial is quite straigthforward just remember to assoicate the following IAM roles to the service account:

* `roles/billing.viewer` to allow accessing the associated GCP project
* `roles/bigquery.dataViewer` to allow access to the costs data

Once you have created the service account you need to create the key that will be used by CCM to connect to your GCP account data.

Doing this is quite easy, you can follow the GCP official tutorial [here](https://cloud.google.com/iam/docs/keys-create-delete). Just remember to select `JSON` as the `Key type`.

Don't forget to save the `access key json file` generated, since you'll have to add it to a cycloid credential later.

#### 2. Setup cloud billing data export to BigQuery[​](#2-setup-cloud-billing-data-export-to-bigquery "Direct link to 2. Setup cloud billing data export to BigQuery")

If billing export is not already configured for your project, you can go on GCP console and lookup for the `billing accounts` page.

Once in this page, click on the on the `billing export` in the left menu.

Then you can enable the export by configuring the different types of data to export. In the case of CCM, it is required to enable `detailed usage cost data` since its the most complete data and hence the one that allows for a more accurate analysis of your costs.

For this click on `edit settings` of `detailed usage cost`. You can then follow the official setup tutorial [here](https://cloud.google.com/billing/docs/how-to/export-data-bigquery-setup#enable-bq-export).

tip

* Be sure to check that you have the rigth access to enable the data export! You must at least have the roles: roles/billing.costsManager or roles/billing.admin and roles/bigquery.user
* Verify that `BigQuery Data Transfer Service API` is enabled. You can do this by following the tutorial [here](https://cloud.google.com/billing/docs/how-to/export-data-bigquery-setup#api)

Once you finish enabling the export, don't forget to save the `project ID`, the `billing dataset` and also the `billing account ID` somewhere, since you'll need it to configure the CCM account later.

## Quickstart[​](#quickstart "Direct link to Quickstart")

note

Before advancing with this tutorial, make sure to verify that you have all the pre-requistes as defined in the section above of this page.

To start you need to setup a Cloud Cost Management account.

For this you should:

1. Navigate to the `FinOps & GreenOps` section in the Cycloid UI.
2. Click on the button `Add account`, this will bring to the menu of your existing credentials.

![](/assets/images/ccm-quickstart-new-account-529dac2675cdddee690748564752afee.png)

3. Create a new cloud credential by clicking on the button `Add new credential` (In case you have previously created one you can just select the credential from the list and skip to the point 5 of this tutorial).

![](/assets/images/ccm-quickstart-new-cred-902bea6b82b38ac3c225d8615ca55c7b.png)

4. You should then define a `name` to associate to the credential, select the `type` of Provider (AWS, GCP or Azure) and depending on the type selected different `credentials parameters` will be required.

   Depending on your provider different parameters are required to collect the data, as mentioned during the pre-requisites section:

* ![AWS](/img/ccm/aws-logo.png)
* ![Azure](/img/ccm/azure-logo.png)
* ![GCP](/img/ccm/gcp-logo.png)

In the case of AWS you should specify the access key previously created in the parameters `access_key` and `secret_key`, as you can see in the image bellow.

![](/assets/images/ccm-quickstart-aws-cred-69cab95ff39a305daf4ef024197bb9ee.png)

In the case of Azure you should specify the access key and storage account name previously created in the parameters `account_name` and `access_key`, as you can see in the image bellow.

![](/assets/images/ccm-quickstart-azure-cred-47f03714116b337ea9b3613c78716f52.png)

In the case of GCP you should specify the access key in json format previously created in the parameter `json_key`, as you can see in the image bellow.

![](/assets/images/ccm-quickstart-gcp-cred-559a55282445785678010a9d103a51f4.png)

note

When creating a new credential a notification will apear in the top rigth corner indicating if the creation was successfull or not. Please report to the [credentials](/reference/credentials/.md "Credentials") section of this documentation in case of issues.

5. After you succeffully selected or created the new credential you can click in the `continue` button, that will lead you to the second part of the account configuration. Here depending on the provider you'll have to specify the required parameters so that CCM can retrieve your cloud cost data.

* ![AWS](/img/ccm/aws-logo.png)
* ![Azure](/img/ccm/azure-logo.png)
* ![GCP](/img/ccm/gcp-logo.png)

In the case of AWS you should specify the location of the CUR report, as we saw during the prerequisites section above.

You should specify the parameters `bucket name`, the `location of the manifest file` within the bucket, e.g, `/folder/report-manifest.json` and select the bucket `region` from a dropwdown menu.

![](/assets/images/ccm-quickstart-aws-account-ba0201e11abed348c5b8c2f605373bbe.png)

note

You can find more than one manifest file in the bucket, and you can choose any of them. Each time a new batch of billing files is generated, they are accompanied by a manifest. The manifest file in the account configuration is needed to differentiate between the legacy and current version of the report since the AWS API does not support that and to jump-start the import.

tip

In case you lost this data you can easily retrieve it, by searching Billing and Cost Management, then scroll on the left menu to Data exports. This will show all the exports, just select the one you're interessed and you can edit it to see the data under the Data export storage settings.

In the case of Azure you should specify the location of the data export from the Azure cost management,as we saw during the prerequisites section above.

You should specify the `container name` and the `prefix` corresponding to the path of the files generated, in the format storage directory/exportName.

![](/assets/images/ccm-quickstart-azure-account-835eeb8297fcbe86bc80b541f83677c6.png)

tip

In case you lost this data you can easily retrieve it, by goint to Cost management | Exports, click on your export, and check both Storage directory and Name. If, for example, your Storage directory is type daily and named MyFirstExport, then your prefix will be daily/MyFirstExport.

In the case of GCP you should specify the GCP exports of your billing data in BigQuery,as we saw during the prerequisites section above.

You should select the `project ID`, the `billing dataset` and the `billing table` to use within the dropdown menu.

![](/assets/images/ccm-quickstart-gcp-account-ae04eebad2b6360a8e3fc8ab2c796ea2.png)

tip

In case you lost this data you can easily retrieve it, by goint to billing accounts, scroll down on the left menu to billing exports. Here you'll be able to see the billing dataset data. If you then click on it you'll be able to get the billing table data.

6. After the account is created, an initial data ingestion starts to retrieve your cloud billing data. Depending on the data volumetry it can take up to several minutes to ingest but is generally quite fast
   <!-- -->
   😃

Finally with the data ingestion finish, you'll be able to start using all the CCM features <!-- -->🚀

Feel free to explore the CCM interface yourself or check the concepts section of CCM docs to have a deep dive into all the different tabs of this feature.


---

# Accounts

You can check the CCM accounts by clicking on the `Accounts tab` on the top bar of the feature. Here you can have an overview of all the CCM accounts.

![](/img/ccm/ccm-accounts-overview.png)

<br />

You can check their associated **cloud provider** and **cloud account ID**, **credential used**, the **last import date** and the **account status** (enabled/disabed).

In case you have many different CCM accounts, you can simply search by cloud provider, cloud account ID, credential name or status.

You can also filter by cloud provider.

## Add new account[​](#add-new-account "Direct link to Add new account")

In the account tab you can add new accounts by clicking on the button `Add new account` you will then have to follow the same procedure as we saw in the [quickstart](/reference/cloud-cost-management/.md#quickstart "CCM Quickstart") of this feature.

## Manage existing accounts[​](#manage-existing-accounts "Direct link to Manage existing accounts")

If you wish to change the settings associated to an account, you can do so by clicking on the account that you want to modify.

This will allow to have a more detail view of the account's credential, its configuration, to disable it or to simply delete it.

![](/img/ccm/ccm-account-edit.png)

<br />

note

As of now is not possible to change the credential associated to a CCM account after creation. To change the credential associated, you will need to disable/delete the account and then recreate it.


---

# Dashboard

The Cloud Cost Manager dashboard is the core of this feature. It's where you're able to see the agregated data of all your accounts and by using a set of different views have a more detailed look into it as you may require.

![](/img/ccm/ccm-dashboard.png)

<br />

When you login initially you can observe:

* **Filter sidebar**: with all the parameters that you can use to separate the data and better visualise it
* **Graphical views**: corresponding to the visual representation of your data trough a set of different views so that you can more easily interpretate it

In the next subections we'll go into more detail about each of these aspects.

## Graphical views[​](#graphical-views "Direct link to Graphical views")

Currently there's 2 dashboard that you can use:

* `Overall dashboard`: This is the initial dashboard when you use CCM. It contains all the data of your different cloud providers.

* `Cloud Provider dashboard`: It provides a more detailed view for a selected cloud provider.

You can learn more about them in the subesctions bellow.

### Overall dashboard[​](#overall-dashboard "Direct link to Overall dashboard")

As mentioned this is the initial dashboard when you access CCM. It consists of a set of different visualizations of your cloud cost data.

At the top you have a `sumup view` that includes the total costs of all your cloud providers in a single graphical representation.

Beside it, you will find a summary of all the aggregated carbon footprint data for all the CCM accounts.

![](/img/ccm/ccm-dashboard-overall-view.png)

<br />

Then if you'll scroll down the page you'll see the `providers breakdown`, that as the name mentioned gives a separate graphical representation for each cloud provider.

It details your costs, carbon emission, and energy usage by cloud provider.

![](/img/ccm/ccm-dashboard-providers-breakdown.png)

<br />

If you click on a specific provider you will be redirected to the `Cloud Provider dashboard`.

note

Depending on the time range, some cloud providers may not be displayed here in case there's no available data for the specific range.

Finally at the end of the page you'll find the `overview` that display multiple graphs and a table detailing cost, energy usage, and estimated carbon emissions, by project.

![](/img/ccm/ccm-dashboard-overview.png)

<br />

Projects are identified via the tags defined on the cloud provider hosting the infrastructure, you can learn more about this on the [tag mapping](/reference/cloud-cost-management/concepts/tag-mapping.md "CCM Tag mapping") section.

You can choose to visualize the data as a line or bars graphs.

### Cloud Provider dashboard[​](#cloud-provider-dashboard "Direct link to Cloud Provider dashboard")

As mentioned before this section is acessible by selecting a specific provider in the `providers breakdown` on the Overall dashboard.

It contains a set of graphs and a table detailing the cost, carbon emissions and energy consumption depending on the filters selected.

![](/img/ccm/ccm-clould-provider-dashboard.png)

<br />

You can choose to visualize the data as a line, bars or stacked bar graphs.

The data is grouped according to the selected `group by` filter.

![](/img/ccm/ccm-cloud-provider-dashboard-grouping.png)

<br />

As you can see in the example picture above the data in grouped by the category first and region later.

You should also note, that this dashboard contains more filters then the overall dashboard, allowing for a more fine-grained visualisation of the cloud provider's data.

## Filter sidebar[​](#filter-sidebar "Direct link to Filter sidebar")

This is the component of the dashboard that you will most use when you are analysing your cloud data.

![](/img/ccm/ccm-dashboard-filters.png)

<br />

You can configure the following parameters:

* `Data range`: The range of data that you want to visualize in the dashboard

* `Granularity`: Represents how the data is agregated in the dahsboard. You can select between **daily**, **weekly** or **monthly**

  note

  When using large data ranges, only monthly granularity is available

* `Project and cloud account filter`: Allows you to filter data based on the project tags associated to the cloud objects and the cloud accounts associated to CCM.

  note

  You can select master or linked accounts. This serves to represent the account hierarchy found in cloud providers, where some accounts are part or integrated in others.

* `Currency`: Selects the currency conversion to use, when representating the data. This is something usefull when you have cloud provider costs in different currencies.

Additionally **when using the cloud provider dashboard view**, you can also configure:

* `Region, service and tags filter`: So that you can select the data from a specific region, service or tags.

* `Resource tagging filter`: To specify wheter to select resources that have tags or not.

* `Group by`: Allows to agregate by project, environment, service, region, resource type, cloud account or category. You can agregate in 2 levels, e.g group by cloud account and resource type.

tip

Check the [tag mapping](/reference/cloud-cost-management/concepts/tag-mapping.md "CCM Tag mapping") section to learn more about cloud tags and how to use them to better manage your cloud data in CCM, using filters.

## Notifications[​](#notifications "Direct link to Notifications")

As you will notice as you will use this feature, in the top section of the dashboard, you'll be shown notifications related to your CCM accounts activity.

These notifications can include tips about CCM functionalities, data imports in progress or failed account imports for example.

![](/img/ccm/ccm-top-banner-area.png)

<br />

note

All the notifications can be turned off by simply clicking on the 'x' button at the rigth end corner of it.


---

# Tag mapping

You can check the CCM accounts by clicking on the Accounts tab on the top bar of the feature.

When using cloud providers a recommended best practice is to attach tags to your cloud objects, in the form key-value pairs, e.g. `env=prod`, to allow for better organization and readibility to your cloud infrastructure.

In the case of CCM, we take advantage of this practice to set up the Project and Environment parameters.

In fact, at Cycloid we always setup these tags across all the infrastructure that we manage.

In case your infrastructure doesn't use this tags, you can use our CCM tag mapping functionality, available by selecting the tab on the top part of this feature with the same name.

It allows to match your existing cloud tags to the pre-defined cycloid ones in CCM for Project and Environment.

This way you'll be able to fully exploit our filters abilities when using the main or the cloud provider CCM dashboards.

There's 2 ways to use tag mapping:

* **Tag selection mode**: select in a dropdown menu the multiple tags to match for both the Environment and Project parameters.

  ![](/img/ccm/ccm-tag-mapping-selection.png)

* **Advance mode**: by specifying a regular expression (based on the [go regex library](https://pkg.go.dev/regexp)) that allows to more map the existing tags. This can be more dificult approach depending on your technical skill level.

  ![](/img/ccm/ccm-tag-mapping-advanced.png)


---

# Config and catalog repositories

## Introduction[​](#introduction "Direct link to Introduction")

**Catalog repositories** are a git repository (or just a branch) containing one or more stacks. They allow you to provide a way to share a catalog of stacks to your users's inside your organization.

**Config repositories** are a git repository (or branch) containing the configuration for your stacks for each environment they are used.

All cycloid projects uses [stacks](/reference/stacks/concepts/stack-concept.md) to perform IaC. The config contains any variables, templates and files that will be merged with the stack to configure the stack for a given project in a specific environment. This notion is explained in the [stack section](/reference/stacks/concepts/stack-concept.md).

You can create as much catalog and configuration repositories as you need.

tip

You can also group everything on one repo and make two orphan branch, `stacks` and `config`.

This can be convenient an allow you to keep stacks and their relative config closer.

See the example below.

## Prerequisites[​](#prerequisites "Direct link to Prerequisites")

* A git source code provider. We support most git provider out there.

* Valid git credentials for your repositories stored in [Cycloid credentials](/reference/credentials/quickstart.md).

  <!-- -->

  * Use a SSH Key credential for SSH urls
  * Use a basic auth credential for HTTPS urls
  * Credentials should have read and write access on repositories.

note

We recommend using SSH Keys, but we also support HTTP tokens (depending on your git provider)

* One repository or one branch for `stacks`
* One repository or one branch for `config`

warning

The specified Git repositories has to be accessible by Cycloid's API and potentially by Cycloid workers if you want to use it inside a pipeline.

important

If your Git server uses a different port than the standard `22`, please note that the url format should follow the [syntax from the git protocol](https://git-scm.com/docs/git-push#_git_urls):

```
ssh://[<user>@]<host>[:<port>]/<path-to-git-repo>

git://<host>[:<port>]/<path-to-git-repo>

http[s]://<host>[:<port>]/<path-to-git-repo>
```

For example, if your git server ssh port is `2222` the url should be as follow:

`ssh://git@your.ssh.server:2222/repo.git`

## Quickstart[​](#quickstart "Direct link to Quickstart")

1. Create two repositories (or two orphaned branches), one for **stacks** and one for **configs**.

The most common and convenient way is to create two orphaned branches.

The most common and handy way is to create two orphaned branches

To do so, simply clone your Git repository and run the following commands:

```
# Config
git checkout --orphan  config
git rm -rf .
touch README.md
git add .
git commit -m "Init config"
git push origin config

# Stack
git checkout --orphan  stacks
git rm -rf .
touch README.md
git add .
git commit -m "Init stacks"
git push origin stacks
```

This will create 2 new orphan branches in the Git repository. Why orphan? Because those branches will contain totally different content. Making them orphan will create completely different branches with their own history in order to avoid merging them together.

2. Generate the related credentials and include in cycloid (lookup [credentials management](/reference/credentials/quickstart.md))

3. In the cycloid console, go to the `Stacks > Catalog repositories` menu.

![](/assets/images/catalog-1-c391d832b00404b97b13407908170e35.png)

4. Fill in the name, the owner, url, credential and branch of the stack repository.

![](/img/catalog/catalog-2.png)

<br />

5. Choose a visibility and assign maintainer (a team) to stacks already present in the git repository.

![](/img/catalog/catalog-4.png)

<br />

You can choose the branch via a dropdown

![](/img/catalog/catalog-3.png)

<br />

You will be able to see your catalog repository on the list, and refresh it.

![](/assets/images/catalog-list-277d31c9e4b10e4676bc1ef0111ecb12.png)

5. Go to `Projects > Config repositories`.

6. Click on `Add config repository`

![](/assets/images/config-create-b0207964c4c8f40ffbdf6e65ff578a94.png)

7. Fill in the name, url, credential and branch of the config repository.

![](/img/catalog/config-create-fill.png)

tip

You can set a config repo as default in your current org.

This is useful to centralize configuration on one repository.

## Concepts[​](#concepts "Direct link to Concepts")

### Default config repo[​](#default-config-repo "Direct link to Default config repo")

You can set a default config repository in an organization.

This repository will be filled as config repo for each new project.

Each project can override locally the config repo they use.

You can change it at project creation:

![](/assets/images/config-default-1035ebfced36f811737011526a508714.png)

Or on the project view, `Configuration` tab:

![](/assets/images/config-default-2-e713f3bff9aa37cf11d24ce553d163ed.png)

### Migrate a config or catalog repository[​](#migrate-a-config-or-catalog-repository "Direct link to Migrate a config or catalog repository")

You may need at some point to change the reference to your config or catalog repo. This may occur for example when changing your git provider.

It is not possible (and shouldn't) to delete a catalog repo that contains stacks that are currently in use in at least 1 project.

So we implemented a way to just change the url of the config repo to update it in-place to all projects.

danger

Be careful to the following steps.

Doing this wrong could break projects an pipeline inside your organization !

Also, migrating a config / catalog repo could mean that you have to update all your legacy project/env that do not use [cycloid special variables](/reference/stacks/concepts/templating.md#special-variables) for config and catalog repo reference.

Finally, you will also loose git references history on concourse git resources.

This migration will take time an put some downtime on your pipeline.

tip

This process is far easier if your ensure that all your stacks use [cycloid special vars](/reference/stacks/concepts/templating.md#special-variables) to reference catalog and config repo.

### Migrate a catalog repository[​](#migrate-a-catalog-repository "Direct link to Migrate a catalog repository")

1. Copy all the stacks from the old catalog repository to the new.

warning

The structure of the repository and the relative path of all the stacks should stay the same !

2. Create or update the Git credential for the new repository in cycloid console.

3. Go to `Stacks -> Catalog repositories` and click on your catalog repository

![](/assets/images/catalog-migrate-1-5100ae3c70c530996a9fa3928328a398.png)

4. You can then edit the catalog repo.

   To change the url, you must click on the padlock on the right of the `URL` field, this will allow you to change the git URL.

   **Make sure it is valid.**

   You can also ajust the `Credential` and `branch` for the new repository.

   Then save your changes.

![](/assets/images/catalog-migrate-2-910c64709ddb2e4c1708e1965ae068c6.png)

5. You can then refresh the catalog repo to ensure that the operation was successful.

   If your are just migrating your stacks to another repo without adding new stacks, you should have this dialog after the refresh:

![](/assets/images/catalog-migrate-3-e7d4d42555d0c813597fae8678bed83d.png)

6. At this stage, you should check all your project and migrate all the reference from the old catalog repo to the new one.

note

If you need help with this proccess, feel free to reach us.

We can help you plan and execute this process and minimise downtime.

### Migrate a config repo[​](#migrate-a-config-repo "Direct link to Migrate a config repo")

Migrating a config repository is similar to the catalog repo.

1. Copy the configs from the old repo to the new.

2. Go to `Projects -> Config repositories` and update the config repo to migrate.

tip

Same as the config repo, you can update the url, credential and branch.

![](/assets/images/config-migrate-1-2d9d4ed850a1e92fb99c9b6b7b9512b4.png)

3. Check and update all your project.


---

# Cost estimation

Cost estimation is a feature that enables the estimation of any Terraform-defined infrastructure. This allows organizations to keep track of any impact that a change to infrastructure could have on finances. It is leveraging Cycloid's open-source project [Terracost](/reference/oss/terracost.md), contributed to, and quickly integrated with any form or pipeline that uses Terraform.

## Introduction[​](#introduction "Direct link to Introduction")

This feature relies on an internal platform task: **Pricing Ingestion:** Internal jobs are scheduled (e.g., weekly) to fetch pricing data from cloud providers (AWS, GCP, Azure) via API or pricing CSV files. The relevant pricing elements (e.g., instance types per region) are extracted and stored in Cycloid's database.

The **cost estimation** is based on our open-source tool [Terracost](/reference/oss/terracost.md), which reads either tfstate or HCL files. It then matches each Terraform resource with the pricing data in the database based on the parameters specified in the resource.

## Prerequisites[​](#prerequisites "Direct link to Prerequisites")

Only if you are running your own dedicated Cycloid platform, ensure the cost estimation feature is enabled. [Here](/cookbook/dedicated-platform/advanced-configurations/enable-cost-estimation.md)

## Quickstart[​](#quickstart "Direct link to Quickstart")

### Testing with CLI[​](#testing-with-cli "Direct link to Testing with CLI")

Using the [Cycloid CLI](https://github.com/cycloidio/cycloid-cli) is the easiest way to get started. The costs of any valid [Terraform plan](https://www.terraform.io/cli/commands/plan) can be estimated using the `terracost estimate` subcommand:

```
$ terraform plan -out=./plan; terraform show -json ./plan > plan.json
$ cy terracost estimate --plan-path plan.json

PLANNEDCOST	PRIORCOST	RESOURCEESTIMATES
71.71     	53.24      	3
```

### While configuring a project[​](#while-configuring-a-project "Direct link to While configuring a project")

When using stackforms you are able to access an estimation of the current stack you are configuring. To do so, fill all the required variables and click "Estimate cost" on the right side.

![Click-Estimation](/assets/images/costestimation-click-estimate-89aa38bf4c0b15e528484e7e4ada7a80.png)

If any estimation was possible, it will then give you its output: ![Click-Estimation](/assets/images/costestimation-estimate-result-e58d2ed1461c29618a415013c11cf2ae.png)

Here you will also be able to dig into the details of that estimation, to see which parts represent each component or which got ignored: ![Click-Estimation](/assets/images/costestimation-estimate-details-f366d48482853b95a2f3c7b563e82fc3.png)

If you happened to change anything related to the project, you'll have to refresh the estimation just like you did the initial one: ![Click-Estimation](/assets/images/costestimation-refresh-estimate-29e242c755733c234f665aa9ebfbff12.png)

At the end of the configuration, you will also have access to a summary of the overall estimation/change. ![Click-Estimation](/assets/images/costestimation-summary-160ec92b32bfb6a6d8f128d877f0ef9e.png)

### In Cycloid pipeline[​](#in-cycloid-pipeline "Direct link to In Cycloid pipeline")

In the context of the pipeline, you can use the [Cycloid Concourse Resource](https://github.com/cycloidio/cycloid-resource) that can be easily plugged in right after a `terraform plan` step and just before a notification mechanism. After configuring the resource, the cost estimation can be performed by specifying `feature: terracost` as parameter, for example:

```
resource_types:
  - name: cycloid-resource
    type: registry-image
    source:
      repository: cycloid/cycloid-resource
      tag: latest

resources:
# Terracost resource
  - name: terracost
    type: cycloid-resource
    source:
      feature: terracost
      api_key: <api-key>
      env: ((env))
      org: ((org))
      project: ((project))
```

Then in your jobs section:

```
- put: tfstate
  get_params:
    output_planfile: true

- put: terracost
  params:
    tfplan_path: tfstate/plan.json
```

#### Example of output[​](#example-of-output "Direct link to Example of output")

![Estimation](/assets/images/costestimation-concourse-b2fb43759f6210a8726a63061756cb8e.png)


---

# Credentials

Cycloid credential manager securly stores, accesses, and distributes secrets like API keys, cloud provider credentials, TLS certificates, SSH keys and more.

We have created an abstraction on top of open sourced [hashicorp vault](https://www.hashicorp.com/products/vault "Hashicorp vault") make the secret management simple, easy and secure for your teams.

Credentials can be used inside pipelines to provisions secret values to all technologies you use (terraform, ansible, and more...).

See for yourself on the next section.


---

# Concepts

## Credential types[​](#credential-types "Direct link to Credential types")

Credential have a type, we have pre-define some common credential types for easier integration with cloud providers and more.

The following types are

1. AWS
2. GCP
3. Azure (storage)
4. SSH
5. Basic Authentication
6. Swift
7. Custom

### AWS[​](#aws "Direct link to AWS")

This type repesent an access key for AWS.

These are used in various situations: fetching logs for the application, from cloudwatch, reading the billing status of your application, managing resources via terraform, etc.

The format is pretty simple, at it is composed of [the access key and the secret key](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html).

![](/img/aws-creds.png)

### GCP[​](#gcp "Direct link to GCP")

A valid Google Cloud Platform [service account key](https://cloud.google.com/iam/docs/creating-managing-service-accounts) in JSON format.

![](/img/gcp-creds.png)

### Azure (storage)[​](#azure-storage "Direct link to Azure (storage)")

Storage account name and access key to use an Azure Blob Storage.

![](/img/azure-creds.png)

### SSH[​](#ssh "Direct link to SSH")

The SSH credentials are in fact SSH private keys, as they are mostly used to access git repositories storing either: pipeline/ansible/terraform configuration or your own application code.

The key has to be a valid SSH private key otherwise you will receive an error.

![](/img/ssh-creds.png)

### Basic Authentication[​](#basic-authentication "Direct link to Basic Authentication")

The Basic Authentication is commonly used on web services. It requires a simple username and password that can be passed as headers or in the url.

![](/img/basic-auth-creds.png)

How to use a GitHub access token

According to the documentation, [**GitHub access tokens**](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token) can be used as `basic_auth` credentials.

1. First, create a `basic_auth` credential and set your **GitHub username** as the `username`, and the **GitHub-generated token** as the `password`.
2. Then, you will be able to create or update your `catalog-repositories` and `config-repositories` with this new `basic_auth` credential.

### Swift[​](#swift "Direct link to Swift")

Swift credential will be used to configure Swift external backend. It's based on V3 authentication against Openstack's Keystone.

![](/img/swift-creds.png)

### Custom[​](#custom "Direct link to Custom")

Custom credential type are basically any number of key/values that you want. That allows to store most type of credentials in the way that you would like: whether http authentication, database password, ansible-vault password, etc.

![](/img/cred.png)

#### Organize your custom credential data[​](#organize-your-custom-credential-data "Direct link to Organize your custom credential data")

Cycloid credentials manager is based on vault, this allows you to create key/value credentials or also key with several fields and values.

Credentials manager lets you specify or override the path of the vault key for advanced user who want to limit the scope of variables based on <https://concourse-ci.org/creds.html>

Before adding stuff in credentials manager, you should ask yourself some questions:

* Do I need a unique credential? ex: a Slack hook url could be the same for all projects.
* Where would my credentials be used? In the pipeline, Terraform or Ansible.
* Is my credential linked to a specific project?
* Will this project have several env? (staging/prod)
* Will my credentials be different for each env?

Those could result in 4 ways to store your credentials:

1. Regular key value

```
# Format
name: value

# Example
slack_hook_url: https://...
```

2. Env named key value

```
# Format
env_name: value

# Example
prod_htaccess: foo
staging_htaccess: bar
```

3. Key containing value for each envs

```
# Format
name:
  Env: value
  Env2: value

# Example
htaccess:
  prod: foo
  staging: bar
```

4. Global secret containing several key values for each env

```
# Format
path_name:
  Env_name: value
  Env_name2: value
  Env2_name: value
  Env2_name2: value

# Example
lambda_secrets:
  prod_htaccess: foo
  prod_key: 123
  staging_htaccess: bar
  staging_key: 456
```

This use case could help when using the vault provider in Terraform. For each credential path, you have to define it in Terraform to use it. It might be easier for example to declare all secret env vars for a lambda in the same path instead of splitting them into several paths.


---

# Manipulate credentials using the API

<!-- -->

## Create a credential[​](#create-a-credential "Direct link to Create a credential")

Lookup [API Documentation](/api/#tag/Organization-Credentials/operation/createCredential) for more informations.

### Custom credentials[​](#custom-credentials "Direct link to Custom credentials")

create\_custom.sh

```
# This example creates a custom credential
# Custom credentials allows you to populate
# any keys/values you want in a credential

org="<your_org>"
credential_name="My custom credential name"
# Credential canonical and path can be the same
credential_canonical="my-custom-credential-canonical"
username="<your_username>" # Not required

# A valid api_key with the following permissions
# - organization:credential:create
api_key="<your_api_key>"

# Pass in a valid json
# See api docs for more info: https://docs.cycloid.io/api/#operation/createCredential
read -r -d '' credential_data <<EOF
{
  "name": "${credential_name}",
  "type": "custom",
  "canonical": "${credential_canonical}",
  "path": "${credential_canonical}",
  "raw": {
    "raw": {
      "my_cool_key": "cool_value",
      "my_cool_other_key": "other_value"
      }
  },
  "description": "A nice description for your credential.",
  "owner": "${username}"
}
EOF

echo "Create a credential"
curl -X POST \
  -H "Content-type: application/vnd.cycloid.io.v1+json" \
  -H "authorization: Bearer ${api_key}" \
  -d "${credential_data}" \
  "https://http-api.cycloid.io/organizations/${org}/credentials" |
  jq .
```

### AWS credentials[​](#aws-credentials "Direct link to AWS credentials")

create\_aws.sh

```
# This example creates a custom credential
#

org="<your_org>"
credential_name="My aws credential name"
# Credential canonical and path can be the same
credential_canonical="my-aws-credential-canonical"
username="<your_username>" # Not required

# A valid api_key with the following permissions
# - organization:credential:create
api_key="<your_api_key>"

# Pass in a valid json
# See api docs for more info: https://docs.cycloid.io/api/#operation/createCredential
read -r -d '' credential_data <<EOF
{
  "name": "${credential_name}",
  "type": "aws",
  "canonical": "${credential_canonical}",
  "path": "${credential_canonical}",
  "raw": {
    "access_key": "<your_access_key>",
    "secret_key": "<your_secret_key>"
  },
  "description": "A nice description for your credential.",
  "owner": "${username}"
}
EOF

echo "Create a credential"
curl -X POST \
  -H "Content-type: application/vnd.cycloid.io.v1+json" \
  -H "authorization: Bearer ${api_key}" \
  -d "${credential_data}" \
  "https://http-api.cycloid.io/organizations/${org}/credentials" |
  jq .
```

### SSH credentials[​](#ssh-credentials "Direct link to SSH credentials")

create\_ssh.sh

```
# This example creates a ssh key credential
# It will contain only a ssh_key attribute containing a private ssh key

org="<your_org>"
credential_name="My ssh credential name"
# Credential canonical and path can be the same
credential_canonical="my-ssh-credential-canonical"
username="<your_username>" # Not required

# A valid api_key with the following permissions
# - organization:credential:create
api_key="<your_api_key>"

# Pass in a valid json
# See api docs for more info: https://docs.cycloid.io/api/#operation/createCredential
read -r -d '' credential_data <<EOF
{
  "name": "${credential_name}",
  "type": "ssh",
  "canonical": "${credential_canonical}",
  "path": "${credential_canonical}",
  "raw": {
    "ssh_key": "$(cat "/path/to/private/key")"
  },
  "description": "A nice description for your credential.",
  "owner": "${username}"
}
EOF

echo "Create a credential"
curl -X POST \
  -H "Content-type: application/vnd.cycloid.io.v1+json" \
  -H "authorization: Bearer ${api_key}" \
  -d "${credential_data}" \
  "https://http-api.cycloid.io/organizations/${org}/credentials" |
  jq .
```

## Update a credential[​](#update-a-credential "Direct link to Update a credential")

get.sh

```
# This example update a existing credential

org="<your_org>"
credential_name="My custom credential name"
credential_canonical="my-custom-credential-canonical"
username="<your_username>" # Not required

# A valid api_key with the following permissions
# - organization:credential:update
api_key="<your_api_key>"

# Pass in a valid json
# See api docs for more info:
# https://docs.cycloid.io/api/#operation/updateCredential
read -r -d '' credential_data <<EOF
{
  "name": "${credential_name}",
  "type": "custom",
  "canonical": "${credential_canonical}",
  "path": "${credential_canonical}",
  "raw": {
    "raw": {
      "my_cool_key": "cool_value",
      "my_cool_other_key": "updated_value"
      }
  },
  "description": "A nice description for your credential.",
  "owner": "${username}"
}
EOF

echo "Update a credential"
curl -X PUT \
  -H "Content-type: application/vnd.cycloid.io.v1+json" \
  -H "authorization: Bearer ${api_key}" \
  -d "${credential_data}" \
  "https://http-api.cycloid.io/organizations/${org}/credentials/${credential_canonical}" |
  jq .
```

## List all credentials in an org[​](#list-all-credentials-in-an-org "Direct link to List all credentials in an org")

list.sh

```
org="<your_org>"
api_key="<your_api_key>"

# Requires those permissions:
# - organization:credential:list
# Enpoint documentation: https://docs.cycloid.io/api/#operation/listCredentials
echo "List credentials"
curl -X GET \
  -H "Content-type: application/vnd.cycloid.io.v1+json" \
  -H "authorization: Bearer ${api_key}" \
  "https://http-api.cycloid.io/organizations/${org}/credentials?page_index=1&page_size=100" |
  jq .
```

## Get a credential[​](#get-a-credential "Direct link to Get a credential")

get.sh

```
org="<your_org>"
# Must be lowercase, with only '-' or '_'
credential_canonical="<credential_canonical>"

# An api key with the following permissions:
# - organization:credential:read
api_key="<your_api_key>"

echo "Get a credential"
curl -X GET \
  -H "Content-type: application/vnd.cycloid.io.v1+json" \
  -H "authorization: Bearer ${api_key}" \
  "https://http-api.cycloid.io/organizations/${org}/credentials/${credential_canonical}" \
  | jq .
```

## Delete a credential[​](#delete-a-credential "Direct link to Delete a credential")

delete.sh

```
# This example delete a existing credential

org="<your_org>"
credential_canonical="my-custom-credential-canonical"

# A valid api_key with the following permissions
# - organization:credential:delete
api_key="<your_api_key>"

# Pass in a valid json
# See api docs for more info:
# https://docs.cycloid.io/api/#operation/updateCredential
echo "Delete a credential"
curl -X DELETE \
  -H "Content-type: application/vnd.cycloid.io.v1+json" \
  -H "authorization: Bearer ${api_key}" \
  "https://http-api.cycloid.io/organizations/${org}/credentials/${credential_canonical}" |
  jq .
```


---

# Manipulate credentials using the CLI

<!-- -->

## Create a credential[​](#create-a-credential "Direct link to Create a credential")

create.sh

```
# You need an API key with the following permissions
# - organization:credential:create

# login using your api_key
cy login --org my-org --api-key "<your_api_key>"

# create a credential for basic authentication
cy --org my-org credential create basic_auth --name foo --username my-username --password my-password

# create a credential for SSH
cy --org my-org credential create ssh --name foo --ssh-key /path/to/private/key

# create a credential for AWS
cy --org my-org credential create aws --name foo --access-key foo --secret-key bar

# create a credential for Azure
cy --org my-org credential create azure --name foo --client-id myid --client-secret mysec --subscription-id mysub --tenant-id mytenant

# create a credential for Azure storage
cy --org my-org credential create azure_storage --name foo --account-name myaccount --access-key mykey

# create a credential for GCP
cy --org my-org credential create gcp --name foo --json-key /path/to/json/key

# create a credential for Elasticsearch
cy --org my-org credential create elasticsearch --name foo --username foo --password bar --ca-cert /path/to/cert

# create a credential for Swift
cy --org my-org credential create swift --name foo --username foo --password bar --tenant-id mytenant --auth-url url --domain-id mydomain
```

## List all credentials in an org[​](#list-all-credentials-in-an-org "Direct link to List all credentials in an org")

list.sh

```
# This action require an API key with the following permissions
# - organization:credential:list

org="<your_org>"

cy login --org "$org" --api-key "$API_KEY"
cy --org "$org" credential list
```

## Get a credential[​](#get-a-credential "Direct link to Get a credential")

get.sh

```
# This action require an API key with the following permissions
# - organization:credential:read

org="<your_org>"

cy login --org "$org" --api-key "$API_KEY"
cy --org "$org" credential get --canonical "<credential_canonical>"
```

## Delete a credential[​](#delete-a-credential "Direct link to Delete a credential")

delete.sh

```
# This action require an API key with the following permissions
# - organization:credential:delete

org="<your_org>"
cy login --org "$org" --api-key "$API_KEY"
cy --org "$org" credential delete --canonical "<credential_canonical>"
```


---

# Quickstart

## Interface[​](#interface "Direct link to Interface")

Credential management is made at project level inside the *Security->Credential* tab on the interface.

![Credential tab](/assets/images/interface-1-6f0673076207800d1e47ddb1070df056.png)

From here you can create, edit and delete credentials.

### Create a credential[​](#create-a-credential "Direct link to Create a credential")

You can create a credential by using the *Add credential* button on the top left corner of the credentials panel.

![](/img/credentials/interface-2.png)

You will be in the *Create credential view*. To create a credential you must fill the following fields:

* **Name**: (required) The pretty name of your credential. This is used only for display on the interface.
* **Description**: (optional) a description for your credential
* **Path**: (required) this field is derived from the `Name` attribute, but you can override it if you want by click
* **Type**: (required) you must choose a credential type. Credential types are important, we created some integrations inside cycloid depending on the credential type. The more commong are the types used for cloud providers (AWS, GCP, Azure) and SSH Keys. If you want to create a custom credential, use the custom type, that way you will be able to fill key and values as you see fit.

Once you chose the type of credential, you will be able to fill the values using the provided fields.

See some examples below:

*AWS Credentials*

![](/img/credentials/create-aws.png)

*Custom credentials*

![](/img/credentials/create-custom.png)


---

# Dedicated Platform

<!-- -->

The Cycloid platform offers flexible deployment options to suit your needs:

* **SaaS**: Cycloid is available as a Software as a Service, hosted and managed by us. This option provides convenience, easy scaling, and reduced maintenance, as we handle the infrastructure and updates.

* **Dedicated platform**: Alternatively, Cycloid can be installed on a dedicated platform within your own infrastructure. This option gives you greater control and security over your data, making it ideal for organizations with specific compliance requirements or sensitive data needs.

## Introduction[​](#introduction "Direct link to Introduction")

The Cycloid **Dedicated platform** is composed of multiple components, as illustrated in the following diagram.

![Infrastructure](/assets/images/onprem-c497b70a525c6aa92f3bd1ff479dbb94.png)

* **Cycloid Console**: The user interface for interacting with the Cycloid platform.
* **Cycloid API**: The backend service that handles requests from the Cycloid Console. It processes business logic and interacts with various data stores and services.
* **Cycloid API task-manager**: Performs background tasks and jobs scheduled by the Cycloid platform, such as email notifications and price injections.
* **MySQL**: A relational database used to store structured data for the Cycloid platform.
* **Redis**: Database used as a queuing system where tasks are consumed by the Cycloid API task-manager.
* **Vault**: A secrets management tool used to securely store and manage credentials from Cycloid.
* **Elasticsearch**: A search and analytics engine used by [Cloud Cost Management](/reference/cloud-cost-management/.md).
* **Concourse Server**: It schedules and manages CI pipelines, and coordinates the execution of jobs by Concourse Workers.
* **Concourse Worker**: Executes tasks and jobs as defined in the CI pipelines. Workers perform the actual build, test, and deployment operations as directed by the Concourse Server.
* **PostgreSQL**: A relational database used by the Concourse Server to store pipeline configurations, job states, and other metadata required for CI/CD operations.

## Prerequisites[​](#prerequisites "Direct link to Prerequisites")

* Cycloid provided the **credentials** to access our Container Registry.
* Cycloid provided the **license key** to activate the platform once it is installed.

## Quickstart[​](#quickstart "Direct link to Quickstart")

Cycloid is a container-based application that supports two types of installations:

* **Helm**: For installing Cycloid on a Kubernetes cluster.
* **Ansible**: For installing Cycloid on Linux instances.

Choosing to install Cycloid on Kubernetes or on a dedicated instances depends on your infrastructure and expertise:

* **[Self-Hosted Kubernetes](/cookbook/dedicated-platform/setup-k8s.md)**: Installing on Kubernetes is ideal if you have expertise in managing one, require scalability, flexibility, and easy management of containerized applications. Kubernetes automates deployment, scaling, and management of applications, making it perfect for handling complex, distributed systems with high availability and load balancing.
* **[Self-Hosted Instances](/cookbook/dedicated-platform/setup-onprem.md)**: Installing on a dedicated VM is a good choice if you prefer simplicity, control, and have specific hardware requirements. Instances provide a stable and isolated environment at a limited cost.
* **[Self-Hosted platforms for evaluation](/cookbook/getting-started/platform-teams/installation.md)**: Describes Self-Hosted platforms for evaluation, training or test purposes.

Additionally:

* **[Advanced Configurations](/cookbook/dedicated-platform/advanced-configurations/.md)**: Detailed and customizable settings that allow users to optimize and tailor a system's performance and functionality beyond the basic setup.


---

# Troubleshooting

## Cycloid API[​](#cycloid-api "Direct link to Cycloid API")

### Database migration fails[​](#database-migration-fails "Direct link to Database migration fails")

`Error: Unexpected message from the external service Database: Dirty database version 1583334924`

When the Cycloid API starts, it runs a database migration. If the migration fails, here are the most common reasons:

* Insufficient Database Privileges: The user configured to run the migration does not have the necessary permissions (e.g., CREATE, ALTER, INSERT).
* Resource Limitations: The database server runs out of resources (e.g., memory, disk space).
* Previous installation: A different version of Cycloid is already installed on the database.
* [Azure Mysql flexible-server](https://learn.microsoft.com/en-us/azure/mysql/flexible-server/concepts-limitations#generated-invisible-primary-keys): Makes sure `sql_generate_invisible_primary_key` is set to `OFF`

### How to restart a service ?[​](#how-to-restart-a-service- "Direct link to How to restart a service ?")

If you have to manually restart a services, it can be done with the following commands

* Cycloid Self-Hosted Instances
* Cycloid Self-Hosted Kubernetes

Example with `cycloid_core` (cycloid-api\_container, cycloid-frontend\_container and nginx\_container)

```
ansible -u admin -b -i inventory  'cycloid_core:children' -a "systemctl restart cycloid-api_container cycloid-frontend_container nginx_container"
```

Example with `cycloid-api`

```
kubectl delete pod -l app.kubernetes.io/name=api
```

## Worker[​](#worker "Direct link to Worker")

### Run local Docker worker[​](#run-local-docker-worker "Direct link to Run local Docker worker")

For testing or Proof of Concept (POC) purposes, instead of using a dedicated worker, you can run one from your laptop using Docker.

To do this, you need to define a few environment variables and use the `cycloid/local-worker` Docker image.

```
export SCHEDULER_HOST="<cycloid_scheduler ip>"
export SCHEDULER_PORT="2222"
export TSA_PUBLIC_KEY="$(cat keys/id_rsa.pub)"
export CYCLOID_TEAM_ID="<from the console ci_team_member>"
export CYCLOID_WORKER_KEY="$(cat keys/id_rsa | base64 -w 0)"

docker run -it --rm --privileged --name cycloid-worker -e SCHEDULER_HOST=$SCHEDULER_HOST \
                                                       -e SCHEDULER_PORT=$SCHEDULER_PORT \
                                                       -e TSA_PUBLIC_KEY="$TSA_PUBLIC_KEY" \
                                                       -e TEAM_ID=$CYCLOID_TEAM_ID \
                                                       -e WORKER_KEY=$CYCLOID_WORKER_KEY \
                                                       cycloid/local-worker
```

* `SCHEDULER_HOST`: The URL to access Concourse web.
* `SCHEDULER_PORT`: The port used for Concourse web/TSA (default is `2222`).
* `TSA_PUBLIC_KEY`: The public key used by Concourse. By default, it is generated in `keys/id_rsa.pub`.
* `TEAM_ID`: From the web interface, go to your Organization detail view and copy the `ci_team_member`.
* `WORKER_KEY`: The worker key allowed on Concourse TSA. By default, it is generated in `keys/id_rsa`.

## Vault[​](#vault "Direct link to Vault")

### Container does not start correctly[​](#container-does-not-start-correctly "Direct link to Container does not start correctly")

Your Vault is probably sealed. Run the following playbook to unseal it

* Cycloid Self-Hosted Instances
* Cycloid Self-Hosted Kubernetes

```
ansible-playbook -u admin -b -i inventory vault_unseal.yml
```

```
scripts/vault-unseal.sh
```

### How locally access to Vault ?[​](#how-locally-access-to-vault- "Direct link to How locally access to Vault ?")

* Cycloid Self-Hosted Instances
* Cycloid Self-Hosted Kubernetes

```
docker exec -e VAULT_SKIP_VERIFY=true -it vault vault status ...
```

Connect to the `vault` pod

```
VAULT_TOKEN=$(jq -r  .root_token scripts/.out/vault-init.json)
kubectl exec -it cycloid-vault-0 -- env VAULT_TOKEN=$VAULT_TOKEN /bin/sh
vault status
vault list cycloid/
```

### Validate authentication manually[​](#validate-authentication-manually "Direct link to Validate authentication manually")

To validate Vault AppRole authentication, you can [use curl](https://developer.hashicorp.com/vault/docs/auth/approle#via-the-api) with the previously created AppRole ID and Secret ID.

To verify the entire workflow end-to-end, you can also test it directly from the Cycloid API container using:

```
curl \
    --request POST \
    --data '{"role_id":"'$VAULT_ROLE_ID'","secret_id":"'$VAULT_SECRET_ID'"}' \
    $VAULT_URL/v1/auth/approle/login
```

## Redis (Queue)[​](#redis-queue "Direct link to Redis (Queue)")

### How to monitoring and administering Asynq queues[​](#how-to-monitoring-and-administering-asynq-queues "Direct link to How to monitoring and administering Asynq queues")

[Asynqmon](https://github.com/hibiken/asynqmon) is a web UI tool for monitoring and administering Asynq queues. It can be used to verify job executions such as Cloud Cost Management account ingestions.

Please follow these steps to run Asynqmon and connect it to Redis:

* Cycloid Self-Hosted Instances
* Cycloid Self-Hosted Kubernetes

Turn `cycloid_cache_mon_install` to `true` to install the Asynqmon container on the `cycloid_cache` instance with Ansible.

environments/cycloid.yml

```
cycloid_cache_mon_install: true
```

Alternatively, you can follow the [Asynqmon example](https://github.com/hibiken/asynqmon?tab=readme-ov-file#examples) to run it manually.

To simplify the process, we suggest exposing your Redis service locally with `port-forward`, then running Asynqmon as a Docker container.

Expose the **Redis** service locally

```
kubectl port-forward svc/cycloid-redis-master 6379:6379 --address='127.0.0.1' &
```

Run a local Asynqmon container and expose it on port `8080`

```
# Note: remove REDIS_INSECURE_TLS if you are not using TLS
docker run --rm --network="host" -e REDIS_INSECURE_TLS=true \
                                 -e REDIS_ADDR="127.0.0.1:6379" \
                                 -e REDIS_PASSWORD="password" \
                                 -p 8080:8080 hibiken/asynqmon
```

Open your browser and go to <http://localhost:8080> to access the Asynqmon dashboard. This will allow you to monitor the status of the Redis queue and gain more insights into job executions.

## Cycloid Database (Mysql)[​](#cycloid-database-mysql "Direct link to Cycloid Database (Mysql)")

### How locally access to the cycloid database ?[​](#how-locally-access-to-the-cycloid-database- "Direct link to How locally access to the cycloid database ?")

* Cycloid Self-Hosted Instances
* Cycloid Self-Hosted Kubernetes

```
eval $(grep 'DB_' /etc/default/cycloid-api|sed -E "s/([^=]+)=(.*)/\1='\2'/")
mysql --protocol=TCP -u$DB_USER -p$DB_PWD -h $DB_HOST $DB_NAME

## Example
# Backup
mysqldump -f --set-gtid-purged=OFF --skip-tz-utc --no-tablespaces --single-transaction --column-statistics=0 -u$DB_USER -p$DB_PWD -h $DB_HOST $DB_NAME > /opt/cycloid.sql

# Restore
mysql --protocol=TCP -u$DB_USER -p$DB_PWD -h $DB_HOST $DB_NAME < /opt/cycloid.sql
```

Connect to the `cycloid-api` pod to access the database

```
API_POD=$(kubectl get pods -l app.kubernetes.io/name=api -o json | jq -r  .items[0].metadata.name)
kubectl exec -it $API_POD -c api -- bash
apk add --no-cache mysql-client mariadb-connector-c
mysql --protocol=TCP --skip-ssl-verify-server-cert -u$DB_USER -p$DB_PWD -h $DB_HOST $DB_NAME
```

## Concourse Database (Postgres)[​](#concourse-database-postgres "Direct link to Concourse Database (Postgres)")

### How locally access to the concourse database ?[​](#how-locally-access-to-the-concourse-database- "Direct link to How locally access to the concourse database ?")

* Cycloid Self-Hosted Instances
* Cycloid Self-Hosted Kubernetes

Install postgresql-client

```
apt install curl ca-certificates
install -d /usr/share/postgresql-common/pgdg
curl -o /usr/share/postgresql-common/pgdg/apt.postgresql.org.asc --fail https://www.postgresql.org/media/keys/ACCC4CF8.asc
sh -c 'echo "deb [signed-by=/usr/share/postgresql-common/pgdg/apt.postgresql.org.asc] https://apt.postgresql.org/pub/repos/apt $(lsb_release -cs)-pgdg main" > /etc/apt/sources.list.d/pgdg.list'
apt-get update
apt-get install postgresql-client-17 -y
```

```
eval $(grep 'CONCOURSE_POSTGRES' /etc/default/concourse-web|sed -E "s/([^=]+)=(.*)/\1='\2'/")
PGPASSWORD="$CONCOURSE_POSTGRES_PASSWORD" psql -h $CONCOURSE_POSTGRES_HOST -U $CONCOURSE_POSTGRES_USER -d $CONCOURSE_POSTGRES_DATABASE

## Example
# Backup
PGPASSWORD=$(grep CONCOURSE_POSTGRES_PASSWORD /etc/default/concourse-web | sed 's/CONCOURSE_POSTGRES_PASSWORD=//') pg_dump -h $CONCOURSE_POSTGRES_HOST -U $CONCOURSE_POSTGRES_USER $CONCOURSE_POSTGRES_DATABASE > base.sql

# Clean old Postgres Databases
# rm /opt/cycloid/concourse-db/* -rf

# Restore
PGPASSWORD=$(grep CONCOURSE_POSTGRES_PASSWORD /etc/default/concourse-web | sed 's/CONCOURSE_POSTGRES_PASSWORD=//') psql -h $CONCOURSE_POSTGRES_HOST -U $CONCOURSE_POSTGRES_USER -f base.sql $CONCOURSE_POSTGRES_DATABASE
```

Connect to the `concourse-web` pod to access the database

```
CONCOURSE_POD=$(kubectl get pods -l app=cycloid-concourse-web -o json | jq -r  .items[0].metadata.name)
kubectl exec -it $CONCOURSE_POD -c cycloid-concourse-web  -- bash

apt-get update; apt-get install postgresql-client -y
PGPASSWORD=$CONCOURSE_POSTGRES_PASSWORD psql -h $CONCOURSE_POSTGRES_HOST -U $CONCOURSE_POSTGRES_USER -d $CONCOURSE_POSTGRES_DATABASE
```

## Pipelines[​](#pipelines "Direct link to Pipelines")

### Connect on a running job[​](#connect-on-a-running-job "Direct link to Connect on a running job")

To ease pipeline debugging, we provide the `cycloid-intercept` script. It can be used to enter into a job's task.

To connect to your pipeline job using cycloid-intercept, follow these steps:

* Open the Cycloid console in your web browser.
* Navigate to the pipeline job you want to connect to by clicking on it.
* Copy the URL from your browser's address bar. The URL should look similar to: `https://<console_url>/organizations/<organization>/projects/<project>/environments/<environnement>/pipelines/<pipeline>/jobs/<job>/builds/`

Use the copied URL with the `cycloid-intercept` command.

* Cycloid Self-Hosted Instances
* Cycloid Self-Hosted Kubernetes

`cycloid-intercept` is located in the **cycloid-api hypervisor** (`/usr/local/bin/cycloid-intercept`).

Example:

```
cycloid-intercept https://18.200.64.222/organizations/cycloid/projects/test/environments/staging/pipelines/test-staging/jobs/deploy/builds/2
  org: cycloid
  pipeline: test-staging
  job: deploy

  1: build #2, step: git_config-terraform, type: get
  2: build #2, step: git_stack-terraform, type: get
  3: build #2, step: merge-stack-and-config, type: task
  choose a container: 3

/tmp/build/d95ecfe0 # ls merged-stack/
main.tf         main.tf.sample  module-onprem   outputs.tf      provider.tf     tag             versions.tf
```

note

`cycloid-intercept` need to be run as **root** or with **sudo**.

Connect to the Cycloid API pod and run the `cycloid-intercept.sh` script

```
API_POD=$(kubectl get pods -l app.kubernetes.io/name=api -o json | jq -r  .items[0].metadata.name)
kubectl exec -it $API_POD -c api -- bash
apk add --no-cache mysql-client mariadb-connector-c
wget https://cycloid-onprem-helm-charts.s3.eu-west-1.amazonaws.com/cycloid-intercept.sh

bash cycloid-intercept.sh https://18.200.64.222/organizations/cycloid/projects/test/environments/staging/pipelines/test-staging/jobs/deploy/builds/2
  org: cycloid
  pipeline: test-staging
  job: deploy

  1: build #2, step: git_config-terraform, type: get
  2: build #2, step: git_stack-terraform, type: get
  3: build #2, step: merge-stack-and-config, type: task
  choose a container: 3

/tmp/build/d95ecfe0 # ls merged-stack/
main.tf         main.tf.sample  module-onprem   outputs.tf      provider.tf     tag             versions.tf
```

## Report[​](#report "Direct link to Report")

To resolve issues with your on-premises setup, you can create and send a debug report to Cycloid by running the `report.yml` playbook. This report will connect to the servers specified in your `inventory` file and collect system, network, and service information.

The collected report will be:

* Compressed with `tar`
* Encrypted with `gpg`
* Sent to `pastefile.owl.cycloid.io` using curl

**Create a report**

* Cycloid Self-Hosted Instances
* Cycloid Self-Hosted Kubernetes

```
ansible-playbook -u admin -b -i inventory report.yml
```

The last step should display a **pastefile.owl.cycloid.io url** and a **secret** to share with Cycloid team.

```
TASK [Report created, please share the following output] **********************************************************************************************************************************************************************************************************************************
ok: [localhost -> 127.0.0.1] => {
    "secret.stdout_lines": [
        "Report have been saved under /tmp/debug-2020-07-03-16:47:35.tar.gz.gpg",
        "",
        "Please share this url and secret to cycloid team: ",
        "",
        "https://pastefile.owl.cycloid.io/746f14db69b52c418c9857d295d5cb5a",
        "secret: HuxsQMc-gMaiYFA0SgwEp074-t7jTx0O"
    ]
}
```

In more specific case, cycloid might need database dump or sensitive information, to allow it `cycloid_report_sensitive` variable can be used when running the playbook.

```
ansible-playbook -u admin -b -e cycloid_report_sensitive=True -i inventory report.yml
```

Please follow cycloid instructions

## ElasticSearch[​](#elasticsearch "Direct link to ElasticSearch")

### How to configure onprem local Kibana[​](#how-to-configure-onprem-local-kibana "Direct link to How to configure onprem local Kibana")

* Cycloid Self-Hosted Instances
* Cycloid Self-Hosted Kubernetes

If your Elasticsearch certificate doesn’t sign the docker ip, disable SSL verification.

Edit `/etc/default/elasticsearch` and add:

```
xpack.security.http.ssl.verification_mode=certificate
```

Restart ElasticSearch

```
systemctl restart  elasticsearch_container.service
```

From **Elasticsearch** container, reset kibana user password

```
docker exec -it elasticsearch bash

bin/elasticsearch-create-enrollment-token --scope kibana
```

Now you can connect to Kibana and configure Elasticsearch access via the private ip such `<https://10.1.0.224:9200>`

Please follow elasticsearch chart instructions


---

# Events

## Introduction[​](#introduction "Direct link to Introduction")

Events allow you to track activity in your organizations.

Cycloid automatically produces events like project creation, pipeline triggers and much more. It is also possible to use our API to create and send your own events.

Our API allows you to extend this feature and connect third party software like monitoring software. To give a concrete example, one of our customer wrote a handler, to receive alerts from his own monitoring system and send them to Cycloid events.

That way you can correlate eventual alerts and changes or deployments made on your application. Or trigger logic (pipelines) on events.


---

# Concepts

## Interface[​](#interface "Direct link to Interface")

To access to events, click on the `Events` section of the *Observability* menu on the left.

![Observability Events](/assets/images/observability-events-9401e1c38cd8565af918f86b57f2f6b7.png)

You can also see them in the *Dashboard menu*

![Dashboard Events](/assets/images/dashboard-events-770f5459f5a902fcaa7ddc110145ac22.png)

## Event type and severity[​](#event-type-and-severity "Direct link to Event type and severity")

By default, events have a `severity` attribute who can be `info|warning|error|critical`.

Each event has an attribute `type`, this help filter events on the view, types can be `Cycloid|AWS|Monitoring|Custom`.

By convention, `Cycloid` events are generated by our interface.


---

# Using the CLI

<!-- -->

Pre-requisites

This require a Cycloid API Key with the follow permissions:

To create one, go to `Security->API Keys` menu, create an api key, and add the following permissions:

* `organization:read`

* `organization:update`

* Use the `Manual actions` to add the following permission:

  <!-- -->

  * Actions: `organization:event:**`
  * Resources: `organization:<fill_with_your_org>`

Right now, the CLI can only create events, this is a limitation that will be addressed in future updates.

To create an event:

1. First, login to you `$org`

```
cy --org $your_org login
```

2. Create your event:

```
cy --org $your_org event create --title "A cool title" \
--message "You event message" \
--severity "info" --tag "env=myenv" --tag "multiple_tags=true"
```


---

# Using the Cycloid concourse resource

<!-- -->

Pre-requisites

This require a Cycloid API Key with the follow permissions:

To create one, go to `Security->API Keys` menu, create an api key, and add the following permissions:

* `organization:read`

* `organization:update`

* Use the `Manual actions` to add the following permission:

  <!-- -->

  * Actions: `organization:event:**`
  * Resources: `organization:<fill_with_your_org>`

note

Links:

* [Cycloid resource](https://github.com/cycloidio/cycloid-events-resource/ "Cycloid event resource for concourse.")

You can use the docker image by defining the resource type in your pipeline YAML.

```
resource_types:
- name: cycloid-resource
  type: registry-image
  source:
    repository: cycloid/cycloid-resource
    tag: latest

resources:
- name: cycloid-events
  type: cycloid-resource
  source:
    feature: event
    api_key: ((custom_api-key-admin.key))
    api_url: ($ .api_url $)
    env: ($ .env $)
    org: ($ .org $)
    project: ($ .project $)


jobs:
  - name: test
    plan:
        ...
        on_success:
          do:
            - params:
                message: |
                  Unit test success in $BUILD_PIPELINE_NAME for $BUILD_NAME
                severity: info
                title: $BUILD_PIPELINE_NAME - Unit test success
              put: cycloid-events
```

### Source configuration[​](#source-configuration "Direct link to Source configuration")

`feature`: *required*. The name of Cycloid feature to use, `terracost`, `infrapolicy` or `event`

`api_key`: *required*. The Cycloid API key used to authenticate the resource against Cycloid APIs

`project`: *required*. The name of the Cycloid project

`env`: *required*. The environment name of the Cycloid project

`org`: *required*. The organization name of the Cycloid project

`api_url`: *optional*. Override the default API URL for infrapolicy validation

### Put parameters for `event`[​](#put-parameters-for-event "Direct link to put-parameters-for-event")

`title`: *required*. The title of the event.

`message` or `message_file`: *required*. One have to be specified, `message` message in the event body or `message_file` file path which contain the message for event body.

`type`: *optional*. The type of the event. Currently, only Cycloid, Custom, AWS or Monitoring are allowed.

`severity`: *optional*. The severity of the event. Currently, only info, warn, err or crit are allowed.

`icon`: *optional*. Icon to display. The icons are the ones from Font Awesome. Example: fa-cubes <https://fontawesome.com/search?o=r&m=free&f=classic>

`yaml_vars_file`: *optional*. Load vars from a file that you can use in event message or title. format MYKEY: value usage my title containing vars $MYKEY.

`tags`: *optional*. The tags allow filtering. Example:

```
tags:
foo: bar
```


---

# Using the API

<!-- -->

Pre-requisites

This require a Cycloid API Key with the follow permissions:

To create one, go to `Security->API Keys` menu, create an api key, and add the following permissions:

* `organization:read`

* `organization:update`

* Use the `Manual actions` to add the following permission:

  <!-- -->

  * Actions: `organization:event:**`
  * Resources: `organization:<fill_with_your_org>`

note

Those are examples for practical uses.

You can refer to the API documentation for more precise information.

* [API Events](/api/#tag/Organizations/operation/sendEvent)

##### Create an event[​](#create-an-event "Direct link to Create an event")

```
api_key=<your_api_key>
org=<your_org_canonical>
read -r -d '' data <<EOF
{
  "type": "Monitoring",
  "title": "My cool event",
  "message": "Look how cool it is !",
  "icon": "bluetooth",
  "severity": "info",
  "tags": [
    {
      "key": "env",
      "value": "dev"
    },
    {
      "key": "anything",
      "value": "you-want"
    }
  ],
  "color": "#ffA500"
}
EOF

curl -X POST \
    -H "Authorization: Bearer ${api_key}" \
    -H "accept: application/json" \
    -H "content-type: application/vnd.cycloid.io.v1+json" \
    -d "${data}" \
    "https://http-api.cycloid.io/organizations/${org}/events"
```


---

# Infra Import

![](/img/infra-import.png)

Infra Import is an infrastructure-as-code generator based on [TerraCognita](/reference/oss/terracognita.md), our open source CLI tool. Designed to streamline your infrastructure management. With this tool, you can effortlessly generate reverse Terraform code from existing manually-deployed infrastructure

Connect it to your manually-deployed cloud infrastructure and Infra Import will create your [Stacks](/reference/stacks/concepts/stack-concept.md) and push them to the predefined [Catalog repository](/reference/config-and-catalog-repository/.md).

Our main use cases involve taking over an existing infrastructure:

* Consider a scenario where an individual or a team creates a proof-of-concept (POC) infrastructure. After successfully validating the POC, the infrastructure team aims to transform it into a production template that can be reused for deploying other applications.
* Alternatively, over time, an infrastructure may have already been deployed and used in production. The infrastructure team may now seek to effortlessly migrate it to infrastructure-as-code.

This is where Infra Import comes into play, simplifying the process by automatically generating infrastructure-as-code and state files for a running infrastructure.

## Introduction[​](#introduction "Direct link to Introduction")

Infra Import connects to your cloud provider to retrieve previously created cloud infrastructure, generates associated Terraform code, and stores it in a Git repository. This process requires following a few prerequisite steps to provide Cycloid with the necessary access for these operations.

Additionally, we strongly recommend tagging resources on your cloud provider to enable more specific filtering of what you would like to import.

Disclaimer

Infra Import is a **beta feature** based on our Open-Source Software [Terracognita](https://github.com/cycloidio/terracognita) as well as [AWS](https://registry.terraform.io/providers/hashicorp/aws/latest), [Azure](https://registry.terraform.io/providers/hashicorp/azurerm/latest), [GCP](https://registry.terraform.io/providers/hashicorp/google/latest) and [VMware vSphere](https://registry.terraform.io/providers/hashicorp/vsphere/latest) Terraform providers.

We provide this feature "as is", and some cloud resource imports might not work, even if listed in the Cycloid portal. Common issues could stem from the external Terraform providers mentioned above. For this reason, Infra Import is excluded from our standard support SLA.

Infra Import is not designed to generate fully functional Terraform code. It is the responsibility of your DevOps team to review and adapt the generated code before using it. The goal of Infra Import is to support and empower your DevOps team in creating new Cycloid stacks faster from existing deployed resources on a best-effort basis.

## Prerequisites[​](#prerequisites "Direct link to Prerequisites")

To use Infra Import make sure you have these set up on your Cycloid account:

| prerequisite                                                       | required                     | description                                                                                                            |
| ------------------------------------------------------------------ | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| [Cloud provider credentials](/reference/credentials/concepts.md)   | Yes                          | To allow Infra Import to fetch your cloud resources                                                                    |
| [Catalog repository](/reference/config-and-catalog-repository/.md) | Yes (with write access)      | To store the generated Terraform code in a Cycloid stack format                                                        |
| [Config repository](/reference/config-and-catalog-repository/.md)  | Yes (`Stack & Project` mode) | To store project related artifacts in case you choose to create a project during the Infra Import process              |
| \[Object storage                                                   | Yes (`Stack & Project` mode) | To store the `.tfstate` file. Can be an S3 bucket on AWS, bucket on GCP Cloud Storage, or OpenStack's Swift container. |


---

# Quickstart

Infra Import needs some upfront configuration to be able to fetch the right resources for you, see the previous [prerequisites](/reference/infra-import/.md#prerequisites) section if not already done.

This section will guide you through the process of setting up all the necessary parameters to perform a successful import.

You can start the Infra Import process by:

1. Going to the **Stacks page**
2. Clicking the **"Create a new Stack"** button
3. Selecting the **"Import your infrastructure"** option

## Infra Import start screen[​](#infra-import-start-screen "Direct link to Infra Import start screen")

![Infra Import Start](/assets/images/infraimport-zero-state-af68573f3350f32e68fc2ba6ba1df056.png)

Once you land on the start screen you can choose either to "Create Stack" or "Create Stack & Project". Note that if one of the prerequisites isn't met the feature will be disabled.

| Mode                | Description                                                                                                                                                                                                                                                                                           |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Stack**           | The output of this path will be a Stack that can be used later when creating projects. Choosing this path is optimal in case you'd want to create several stacks one by another, or when you, or someone from your team, will create a project out of the stack at an undetermined time in the future |
| **Stack & Project** | In this scenario Infra Import will create a Stack, Project, an External Backend, if one was configured. This option is great if you'd like to use the imported infrastructure straight away                                                                                                           |

Create Stack & Project

You can choose `Create Stack & Project` mode on the Infra Import start screen. This option allows to additionally create a Project which will be based on the Stack created during the import. In addition of generating a stack, it will create a Project with it and generate a tfstate file for the selected infrastructure.

## Select Provider[​](#select-provider "Direct link to Select Provider")

Here you can simply select the cloud provider from which you would like to fetch the infrastructure resources. As of writing, we currently support `AWS`, `GCP`, `Azure` and `vSphere`. We are planning to add `OpenStack` and `FlexibleEngine` support in the future.

## Configure Provider access[​](#configure-provider-access "Direct link to Configure Provider access")

You can add your cloud provider configuration in this step. It will consist of the already mentioned credentials as well as provider-specific fields (i.e. AWS Region GCP project id, ...)

## Infra Import Filters[​](#infra-import-filters "Direct link to Infra Import Filters")

![Infra Import Filters](/assets/images/infraimport-filters-ae14ae3cab1f8ad310088b98a02ed7a3.png)

tip

You can skip the filters step. In this case, all the supported resources will be fetched from the cloud provider. Bear in mind it may take some time depending on the size of your infrastructure.

This step allows you to narrow down the import to specific resources. It can be useful in case you have multiple applications running on your cloud infrastructure and want to create a separation of concerns with the stacks. There are two ways of filtering resources:

* **Resources filter**: you can pick the resource types that should be imported by Terracognita. Once you select the resource type, Infra Import will connect to your cloud provider and pre-fetch the resources, so that you can review if the resource IDs match your expectations. (Missing resource? [Contact us](https://www.cycloid.io/contact-us)).
* **Tags filter**: if your infrastructure resources are tagged, you can use tags to narrow down the import. Type the tag in a format `key:value` i.e.: `env:production`. You can add multiple tags for fine-grained control.

## Infra Import Variables[​](#infra-import-variables "Direct link to Infra Import Variables")

![Infra Import Variables](/assets/images/infraimport-variables-301ad56a32dc981505fdf91cda946ba5.png)

Once you have the resources selected, you can also choose the attributes which will be turned into Terraform variables.

Variables will help to expose resources attributes as **stack parameters** and StackForms. For example with [**instance\_type**](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/instance#instance_type), can be selected to let users choose the right sizing for their AWS EC2 instance.

## Stack information[​](#stack-information "Direct link to Stack information")

![Infra Import Stack Details](/assets/images/infraimport-stack-7bbe99f69ba72815059029e1d1a8587c.png)

This step allows you to enter information for the Stack you are going to create

* **Catalog repository** sometime called service catalog, define the Git repository where the stack will be stored
* **Keywords** Used to assist in stack discovery and search on the Stacks page

`Name`, `Description`, and `Keywords` will be displayed and used on the Stacks page. It's a good practice to take some time and fill in those fields with meaningful data to aid the future users of the Stacks.

## Project Details *(Stack & Project mode only)*[​](#project-details-stack--project-mode-only "Direct link to project-details-stack--project-mode-only")

![Infra Import Project Details](/assets/images/infraimport-project-info-623fc047a5d42c592fae612c3b0b65a3.png)

This step allows to enter project information:

* **Config repository** The Git repository where the stack config for the project will be stored
* **Environment** The name of the environment to be created within the project, such as `prod`, `staging`, ....

## External Backend Configuration *(Stack & Project mode only)*[​](#external-backend-configuration-stack--project-mode-only "Direct link to external-backend-configuration-stack--project-mode-only")

![Infra Import External Backend](/assets/images/infraimport-external-backend-77b54f9da0d59b4de2543ef5899d1476.png)

This step lets you configure the External Backend - object storage to store your [`.tfstate`](https://www.terraform.io/language/state) file. In addition of storing this file, Cycloid uses the `.tfstate` to create [InfraView](/reference/infraview/.md), live, visual representation of your infrastructure.

## Infra Import Summary[​](#infra-import-summary "Direct link to Infra Import Summary")

![Infra Import Summary](/assets/images/infraimport-summary-911b4f8a9d8d3970b629420823a35607.png)

In this step you can view the summary of all the data that has been added throughout the wizard:

* The Stack card preview
* The Provider details (Also, Project and External Backend info in the `Create Stack & Project` mode)
* A table of selected resource types with the resource IDs and variables. You can expand each list item to see all the related resources/variables

You can go back to the previous steps to make any adjustments. When the configuration looks good click the `Import infrastructure` button to begin the import!

## Infra Import progress[​](#infra-import-progress "Direct link to Infra Import progress")

![Infra Import Progress](/assets/images/infraimport-modal-progress-7876c80f137a521aed5fd36d4b53ebc2.png)

Once the import has started, a modal will be displayed. It shows the status as well as the current progress of the import. Once the import is finished, `The import was successful` notification message will be shown. The modal can be closed before the import is finished though and you can proceed to fulfill other tasks. The import will continue in the background. Cycloid will send you a notification email once it's finished.

You can also check the import status on the related Project/Stack cards on the Projects/Stacks pages. They will have the `importing` label present during the import. Clicking on the Project/Stack card in the `importing` state will open the import progress modal where you can see the detailed log.

| ![](/img/infraimport-stacks-importing.png) | ![](/img/infraimport-projects-importing.png) |
| ------------------------------------------ | -------------------------------------------- |

There may be a situation where the import ends with an error. In this case, a `failed` label will be displayed on the Project/Stack card. You may try retrying the import by clicking the retry icon, or the retry button in the import progress modal.

## Infra Import output[​](#infra-import-output "Direct link to Infra Import output")

Once the import succeeded, the stack reflecting your imported resources should be stored in the selected Catalog repository and visible on Cycloid console. The Stack respects Cycloid principles and can be used on new projects.

When checking on Git, a folder named with your Stack name should be present and contain:

* [.cycloid.yml](/reference/stackforms/concepts/forms-file.md)
* [pipeline](https://concourse-ci.org/pipelines.html)
* [terraform](https://www.terraform.io/intro)

Generated terraform code is structured as terraform [module](https://www.terraform.io/language/modules/syntax) where each file aggregates the resources from the same "category".

Pipeline is the definition of jobs, tasks and variables preconfigured to run `terraform plan/apply` within your project. Terraform changes automatically trigger your pipeline which helps you to get better control of your infrastructure.

For more specific needs, Stack can be improved in a different ways. [Create my own Stack](/cookbook/getting-started/devops-teams/stack-creation/.md) documentation is a good place to start.


---

# Infrapolicies - policy as code

## What's infrapolicies---policy-as-code ?[​](#whats-infrapolicies---policy-as-code- "Direct link to What's infrapolicies---policy-as-code ?")

## Introduction[​](#introduction "Direct link to Introduction")

Infrastructure Policies (InfraPolicy) are an implementation of [Policy as Code](https://developer.hashicorp.com/sentinel/docs/concepts/policy-as-code). The idea is to have fine-grained control over changes across an organization's infrastructures while simultaneously defining validation rules.

The validation process is based on the [Open Policy Agent](https://www.openpolicyagent.org) engine, which allows us to write a set of rules using the [Rego](https://www.openpolicyagent.org/docs/latest/#rego) language to express validation behavior.

The infrastructure changes are represented by changes in the [Terraform Plan](https://www.terraform.io/cli/commands/plan) that must respect the defined rules. For example, you can ensure that tags are applied to all resources or ensure that no instance bigger than `t2.large` has been used, etc.

## Concepts[​](#concepts "Direct link to Concepts")

An InfraPolicy is represented by a `Body` that contains the set of rules and a `Severity` that defines the enforcement level.

#### Body[​](#body "Direct link to Body")

The rules deny or allow changes are written using the [Rego language](https://www.openpolicyagent.org/docs/latest/policy-language). Currently only `allow` and `deny` rules are checked. See examples below:

The *Input* body for the OPA engine during validation will include the following fields:

```
{
    "environment_canonical": "env-example-canonical",
    "project_canonical": "proj-example-canonical",
    "tfplan": {
        ...
    }
}
```

This allows rules in the `Body` code to include checks on `environment_canonical` and `project_canonical` :

```
package example

default allow = false

allow {
    input.project_canonical == "proj-example-canonical"
    input.environment_canonical == "env-example-canonical"
}
```

The `tfplan` represents [Terraform Plan](https://www.terraform.io/cli/commands/plan) in [JSON format](https://www.terraform.io/internals/json-format#plan-representation). All the rules must use [dot notation](https://www.openpolicyagent.org/docs/latest/kubernetes-primer/#dot-notation) to reference specific fields:

```
package example

default allow = false

allow {
    input.tfplan.resource_changes[_].change.after["max_size"] < 5
}
```

`allow` rule must return a direct boolean value

```
package example

default allow = false

allow {
    input.project_canonical == "proj-example-canonical"
}
```

And the `deny` rule must return an array of strings containing the reasons for the failure:

```
package example

deny[reason] {
    not input.project_canonical == "proj-example-canonical"

    reason := sprintf("The project canonical %q is not expected", [input.project_canonical])
}
```

warning

`allow` and `deny` are opposite concepts, this means `allow` will fail if the result of the rule is `false`, and `deny` will fail if the rule is `true`.

The OPA documentation [contains useful information](https://www.openpolicyagent.org/docs/latest/policy-language/#negation) on how to write policies that include deny rules, and defines best practices to follow in order to build reliable policy systems.

#### Severity[​](#severity "Direct link to Severity")

The client checks the Severity level to decide what to do with changes in the event an InfraPolicy has not been respected.

* Critical: the changes must be blocked
* Warning: the changes are blocked but they can be overridden with a manual operation
* Advisory: the changes can be automatically applied but a notification must be sent

#### Status[​](#status "Direct link to Status")

The status can be enabled or disabled. When it is disabled the InfraPolicy will be excluded from the validation process.

## Testing[​](#testing "Direct link to Testing")

The OPA engine has a dedicated command for testing. The best practices suggested in the [OPA testing](https://www.openpolicyagent.org/docs/latest/policy-testing) documentation should be followed. Other than the `opa test` command, the OPA ecosystem has a [Playground](https://play.openpolicyagent.org) that can be used for fast and simple assertions.

## Validation[​](#validation "Direct link to Validation")

In order to validate your [Terraform Plan](https://www.terraform.io/cli/commands/plan) against the defined policies, you can use of the following methods:

### Locally[​](#locally "Direct link to Locally")

[Terraform Plan](https://www.terraform.io/cli/commands/plan) can be validated locally using Cycloid [cli](https://github.com/cycloidio/cycloid-cli.git) with the `validate` subcommand:

```
$ terraform plan -out=./plan; terraform show -json ./plan > plan.json
$ cy infrapolicy validate --plan-path ./plan.json
ADVISORIES      CRITICALS       WARNINGS
1               0               0
```

### In Cycloid pipeline[​](#in-cycloid-pipeline "Direct link to In Cycloid pipeline")

In a pipeline context, a Concourse [Resource](https://github.com/cycloidio/cycloid-resource.git) is available and can be easily plugged right after a `terraform plan` step and just before a notification mechanism.

#### Example of output[​](#example-of-output "Direct link to Example of output")

Validation with advisories, the job is green and display advisories result as metadata:

![Advisories](/assets/images/advisories-concourse-6ec6e1046633f67413902751351ae342.png)

Validation with criticals and/or warnings, the job fails and display result as metadata:

![Criticals](/assets/images/criticals-concourse-66697da9b8ec3e5b9df088477a2d225c.png)

## Setup[​](#setup "Direct link to Setup")

* Create a new policy from the `Security / InfraPolicies` page by clicking on the `Add InfraPolicy` button.

* Fill in the mandatory fields and click on `Save` to add the resource. Enable the policy to include it in the next validation run.

![Create InfraPolicy](/assets/images/create-infra-policy-form-11a87ed1fef8f00ee9137dcd6d49fc57.png)

* Add the pipeline and a validation resource as described [before](#validation).

* Try to submit some unexpected infrastructure changes that go against your policies (e.g. try to double the size of the instance) to see InfraPolicy in action.

## Code examples[​](#code-examples "Direct link to Code examples")

Examples of Rego code for some common use cases. Other examples can be found in the [fugue/regula](https://github.com/fugue/regula/tree/master/rego/rules) or [open-policy-agent/conftest](https://github.com/open-policy-agent/conftest/tree/master/examples) repositories.

#### Tags required[​](#tags-required "Direct link to Tags required")

Allow only resources with defined tags.

```
package example

deny[reason] {
    resource := input.tfplan.planned_values.root_module.resources[_]
    not resource.values.tags

    reason = sprintf("tags required for the resource %q", [resource.address])
}
```

#### Instance type[​](#instance-type "Direct link to Instance type")

Allow only specific types of instances.

```
package example

allowed_instance_types = {
  "t2.medium",
  "t2.large",
  "t2.xlarge"
}

deny[reason] {
    itype := input.tfplan.resource_changes[_].change.after["instance_type"]
    not allowed_instance_types[itype]

    reason = sprintf("instance_type %q is not accepted, use one of the allowed: %v", [itype, allowed_instance_types])
}
```

#### Instance quantity[​](#instance-quantity "Direct link to Instance quantity")

Define the maximum amount of running instances that the Auto Scaling Group can spawn.

```
package example

default allow = false

allow {
    input.tfplan.resource_changes[_].change.after["max_size"] < 5
}
```

#### Only a specific region[​](#only-a-specific-region "Direct link to Only a specific region")

Allow only a certain set of cloud provider regions.

```
package example

default allow = false

allow {
    provider := input.tfplan.configuration.provider_config.aws
    provider.expressions.region.constant_value == "eu-west-1"
}
```

#### Security group required[​](#security-group-required "Direct link to Security group required")

Make the security group mandatory.

```
package example

deny[reason] {
  r := input.tfplan.resource_changes[_]
  r.change.after_unknown.vpc_security_group_ids == true

  reason := "A security group is required"
}
```

#### Specific AMI[​](#specific-ami "Direct link to Specific AMI")

Allow only a specific set of AWS AMI.

```
package example

import input.tfplan as tfplan

allowed_amis = {
  "ami-abc",
  "ami-xyz"
}

deny[reason] {
    ami := tfplan.resource_changes[_].change.after.image_id
    not allowed_amis[ami]

    reason := sprintf("AWS AMI %q is not accepted, use one of the allowed: %v", [ami, allowed_amis])
}
```

#### RDS Backup set[​](#rds-backup-set "Direct link to RDS Backup set")

Allow only RDS databases with a backup set in the production environment.

```
package example

is_production {
    input.environment_canonical == "prod"
}

deny[reason] {
    is_production

    resource := input.tfplan.planned_values.root_module.resources[_]
    resource.type == "aws_db_instance"
    not resource.values.backup_retention_period > 0

    reason = sprintf("Backup is required on production for %q", [resource.address])
}
```


---

# Concepts


---

# Reference


---

# InfraView

<!-- -->

InfraView, powered by [Inframap](https://github.com/cycloidio/inframap/), is a centralized graphical tool designed to provide a comprehensive representation of your infrastructure. It offers unparalleled visibility into your cloud resources and facilitates seamless collaboration across teams.

InfraView leverages Terraform's TFState file to gather information about your infrastructure. By analyzing this file, it creates a visual representation that accurately reflects the state of your cloud environment.

![](/img/overview_populated-diagram.png)

**Key Features:**

1. **Interactive Schema:** The schema generated by InfraView is interactive, allowing users to click on individual resources to access detailed information such as IP addresses, VM sizes, and other relevant details.

2. **Graphical Representation:** InfraView offers a visual depiction of your cloud infrastructure, making it easier to understand complex architectures and relationships between resources.

3. **Collaboration:** InfraView acts as a bridge between different teams involved in managing your infrastructure. By providing a centralized platform for viewing and understanding the infrastructure

## Introduction[​](#introduction "Direct link to Introduction")

To begin with InfraView, start by navigating to your **project** under InfraView tab where you want to visualize your infrastructure. Within the project, InfraView creates schemas for each environment.

As explained in the previous section InfraView rely on our opensource project [infraMap](https://github.com/cycloidio/inframap/) to generate a graph of compatible resources for each cloud providers.

Each cloud provider is handled differently within InfraView's logic to display only relevant resources and comprehend their dependencies and relationships effectively.

To generate schemas, InfraView reads the TFState file. While it's advantageous to configure a [Cycloid global Terraform HTTP backend](/reference/inventory/.md#cycloid-global-terraform-http-backend) for seamless integration with InfraView, an alternative approach involves configuring access to object storage for each cloud provider within your project configuration.

## Prerequisites[​](#prerequisites "Direct link to Prerequisites")

* To use Terraform between versions `0.11` and `0.15.3`
* Use one of the compatibles cloud providers: AWS, Azure, GCP, FlexibleEngine, OpenStack
* Store the Terraform State ideally using Cycloid global Terraform HTTP backend

## Quickstart[​](#quickstart "Direct link to Quickstart")

By default, InfraView should already be configured for all projects if a Cycloid remote Terraform backend has been set up at the organization level.

If it's not configured, follow the steps below:

<!-- -->

Configure a global Cycloid HTTP backend for Terraform

The configuration of a global Terraform HTTP backend in Cycloid must be done at the **Organization** level. Once added to the organization, all new projects created will use this global backend by default.

The global Terraform HTTP backend relies on third-party tfstate file storage such as cloud object storage. It requires you to have previously created an object storage and access keys before proceeding.

**1.** If the access keys are not already present, the first step is to add the previously created access keys to Cycloid credentials. Click on **Credentials** under **Security** in the left menu.

Then, add your credential using the appropriate type. For example, use "AWS" for an AWS S3 bucket:

![Cycloid AWS credentials](/assets/images/aws-step-by-step-creds-f96644246702be68fa4aa81d17bc9a50.jpg)

**2.** The last step is to configure the Cycloid Terraform HTTP backend at the organization level. To do this, click on your **current organization** name at the top right, then select **Organization settings**. In the Settings tab, locate the **Terraform section** and click **configure**.

You will be prompted to choose the type of supported tfstate backend you wish to configure. Depending on the type selected, Cycloid will request global information such as the object storage name and the credentials to use for access.

![terraform-backend](/assets/images/terraform-backend-616c33313d1fa0905c63fc85d181c28f.png)

For specific use cases, you can still override or provide a specific configuration for a project and environment.

To do so, navigate to your **project** environment and access the **Configuration** tab. You'll be prompted to configure a remote Terraform backend for that environment.


---

# Concepts

## Interface[​](#interface "Direct link to Interface")

### Interacting with the Diagram[​](#interacting-with-the-diagram "Direct link to Interacting with the Diagram")

#### Zoom[​](#zoom "Direct link to Zoom")

Utilize the Zoom slider to conveniently adjust the size of elements displayed on the diagram.

![overview\_zoom-slider--zoom](data:image/png;base64,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)

#### Fit to Canvas[​](#fit-to-canvas "Direct link to Fit to Canvas")

Click the "fit to canvas" button next to the Zoom slider to optimize the diagram's layout by automatically adjusting the display to fit all elements within the visible area.

![overview\_zoom-slider--fit-to-canvas](data:image/png;base64,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)

### Interacting with Elements[​](#interacting-with-elements "Direct link to Interacting with Elements")

Hovering over an element triggers a summary popup, providing quick insights into the properties and attributes of the selected component.

![infraview-mouse-hover](/assets/images/infraview-mouse-hover-a1d115e4f9847866600fe615050f69c9.png)

Clicking on an element opens the **right panel**, offering a comprehensive view of all relevant details associated with the selected component.

### Right Panel[​](#right-panel "Direct link to Right Panel")

Upon opening the right panel, users gain access to detailed information about the selected element. This section serves as a centralized hub for exploring and understanding the properties and attributes of various components within the infrastructure.

![overview\_right-panel-open](/assets/images/overview_right-panel-open-0a1238e8d0b27ee89d73f25b4804fe52.png)

#### Header Actions[​](#header-actions "Direct link to Header Actions")

The header actions within the right panel offer convenient functionality to enhance user interaction and navigation.

![overview\_right-panel-actions](/assets/images/overview_right-panel-actions-780303304352e37a1331658fbf9804f3.png)

1. Opens the corresponding Terraform documentation page for the element.
2. Centers the element on the diagram.
3. Closes the right panel.

#### Element Attributes[​](#element-attributes "Direct link to Element Attributes")

Easily copy any value of any property by clicking the desired property field. A copy icon indicates the property value that will be copied when hovered over.

![](/img/overview_right-panel-hover-copy-prop.png)

#### Filtering[​](#filtering "Direct link to Filtering")

Filter properties by entering a search query in the search box. The search filters by property names only, not values. Click the `X` or delete the search box content to show all properties again.

**Example:** Searching for all property keys containing **id**.

![](/img/overview_right-panel-filter-props.png)

### No Configuration and common errors[​](#no-configuration-and-common-errors "Direct link to No Configuration and common errors")

If an environment has not been configured to use **tfstate**, no diagram will be shown. Instead, an **Add configuration** button will initiate the configuration process for that environment.

![](/img/overview_needs-configuration.png)

Errors and a blank diagram will be displayed if there were problems loading the **tfstate** for an environment.

**Example:**

![](/img/overview_s3-config-error.png)


---

# Asset Inventory

<!-- -->

Asset Inventory provides one place to easily view, analyze, and understand all your assets across projects and environments.

Resources within the Cycloid Inventory can be provisioned via API calls or automatically through the Cycloid Terraform HTTP backend.

All resources generated by your projects should be present here, complete with comprehensive details. For instance, if a project creates a cloud instance, it should be listed in the resources inventory, showcasing essential information such as IP address, size, and more.

Moreover, utilizing the asset inventory in conjunction with the Cycloid Terraform HTTP backend offers automation and additional features, including [InfraView](/reference/infraview/.md) for projects utilizing Terraform.

![Inventory](/assets/images/inventory-c355060d9de8441d66cdd593ca073ed9.png)

## Introduction[​](#introduction "Direct link to Introduction")

As mentioned earlier, the asset inventory feature serves as a centralized repository for resources. To begin utilizing it, the initial step is to add resources to the inventory.

Currently, there are two methods to add resources:

1. The most common method involves allowing Terraform to populate our inventory through our Terraform HTTP backend.
2. Alternatively, resources can be manually added using our API, referred to as customer resources.

We recommend following the Terraform HTTP backend method. The following sections outline prerequisites to get started with the asset inventory using the Terraform HTTP backend.

Before continuing with our Cycloid Terraform HTTP backend, you need to understand one key detail: Cycloid will not physically store Terraform tfstate files. Instead, Cycloid will require and utilize object storage solutions such as AWS S3, GCP object store, and others for this purpose.

## Prerequisites[​](#prerequisites "Direct link to Prerequisites")

To utilize the asset inventory with Cycloid Terraform HTTP backend, you need to configure a global Terraform remote object storage at your organization level.

To configure this remote object storage, you must provide access to an actual remote state storage system. Cycloid supports major cloud provider object storage systems such as AWS, GCP, Azure, as well as S3-compatible APIs such as Minio and a few others third-party storages.

For each cloud provider, the required elements include creating object storage and access keys, then adding those access keys into the Cycloid console.

* AWS
* GCP
* Azure

- [**AWS S3 buckets**](https://docs.aws.amazon.com/quickstarts/latest/s3backup/step-1-create-bucket.html).
- **Amazon access key**:
  <!-- -->
  * Require read and write permissions on the previous S3 bucket

* [**GCP object storage bucket**](https://cloud.google.com/storage/docs/creating-buckets):
* [**GCP service account key**](https://cloud.google.com/iam/docs/creating-managing-service-accounts):
  <!-- -->
  * Require read and write permissions on the previous object storage bucket

- [**Azure blob storage and an Azure blob container**](https://docs.microsoft.com/en-us/azure/storage/blobs/storage-blobs-introduction)
- **Azure** [credentials](https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs#authenticating-to-azure)
  * `client_id`, `subscription_id`, `tenant_id`, ...

Save the generated access keys. During the quickstart section, we will use them in Cycloid.

## Quickstart[​](#quickstart "Direct link to Quickstart")

After completing the prerequisites, the first step before using asset inventory with Cycloid Terraform HTTP backend is to configure a remote backend at your organization level.

### Cycloid global Terraform HTTP backend[​](#cycloid-global-terraform-http-backend "Direct link to Cycloid global Terraform HTTP backend")

<!-- -->

The configuration of a global Terraform HTTP backend in Cycloid must be done at the **Organization** level. Once added to the organization, all new projects created will use this global backend by default.

The global Terraform HTTP backend relies on third-party tfstate file storage such as cloud object storage. It requires you to have previously created an object storage and access keys before proceeding.

**1.** If the access keys are not already present, the first step is to add the previously created access keys to Cycloid credentials. Click on **Credentials** under **Security** in the left menu.

Then, add your credential using the appropriate type. For example, use "AWS" for an AWS S3 bucket:

![Cycloid AWS credentials](/assets/images/aws-step-by-step-creds-f96644246702be68fa4aa81d17bc9a50.jpg)

**2.** The last step is to configure the Cycloid Terraform HTTP backend at the organization level. To do this, click on your **current organization** name at the top right, then select **Organization settings**. In the Settings tab, locate the **Terraform section** and click **configure**.

You will be prompted to choose the type of supported tfstate backend you wish to configure. Depending on the type selected, Cycloid will request global information such as the object storage name and the credentials to use for access.

![terraform-backend](/assets/images/terraform-backend-616c33313d1fa0905c63fc85d181c28f.png)

From this point forward, all new projects or environments created in Cycloid will benefit from the default *Cycloid global Terraform HTTP backend*. Resources created using Terraform will be automatically added to the Cycloid inventory.

Refer to the next sections, [How to use Cycloid HTTP backend in Cycloid pipelines](/reference/inventory/concepts.md#how-to-use-it-in-a-pipelines-), if you are writing your own stack and want to learn how to integrate it with the Cycloid inventory.

### Asset inventory[​](#asset-inventory-1 "Direct link to Asset inventory")

To access the asset inventory dashboard, navigate to **Resources** > **Inventory** in the left menu. This will display an overview of all resources associated with your current organization.

![inventory-overview](/assets/images/inventory-overview-150d173bec829ebe235914e5921bf285.png)


---

# Concepts

## Dashboard[​](#dashboard "Direct link to Dashboard")

The inventory comprises the comprehensive list of all resources affiliated with your organization. Upon clicking on a specific resource, you'll view its name, global information, and provider details. Furthermore, all attributes associated with the selected resource will be displayed. For Terraform resources, you'll be able to access all information stored in the tfstate.

![inventory-panel](/assets/images/inventory-panel-b8080f32f520f6327341020931da6897.png)

In addition to keywords, the inventory interface allows filtering resources based on multiple criteria.

**Filters**

* **Project** and **Environments**: Filter resources from a specific Cycloid project/environment entity.
* **Type**: Types of resources you want to select, for example, `aws_instance` or `aws_instance,aws_s3_bucket`.
* **Provider**: Filter resources from a specific Terraform provider.
* **Module**: Filter resources based on the Terraform module they belong to.
* **Label**: Filter on labels that a user could specify when creating a custom resource.

![inventory-filters](/assets/images/inventory-filters-61f1e00d5d3aa73814a9be43489fa35f.png)

Tips

If you intend to integrate the inventory into StackForms, a convenient method to configure the filter for the `cy_inventory_resource` widget is by utilizing the asset inventory dashboard filters. This approach allows you to configure and instantly observe the results of the filters in real-time. Once configured, you can simply click on the **note** icon to generate a StackForms `cy_inventory_resource` configuration. Learn more about the inventory widget in the [dedicated section](/reference/stackforms/reference/widgets/cy_inventory_resource.md). ![inventory-widget-filter](/assets/images/inventory-widget-filter-37e9ad484a360de98fd17f5b3b0870c8.png)

## Terraform resources[​](#terraform-resources "Direct link to Terraform resources")

This can be archived by using our Cycloid Terraform HTTP backend.

It's an actual HTTP backend compatible with [Terraform HTTP remote state backend](https://developer.hashicorp.com/terraform/language/backend/http). But Cycloid will actually not store the tfstate file.

Cycloid **Terraform HTTP remote backend** is a standalone element part of the global inventory feature. It corresponds to an actual Terraform HTTP backend that can be used to remotely store tfstate files.

Cycloid inventory can be used in Cycloid's pipelines or directly in Terraform as a HTTP remote state backend. It enables Cycloid features on top off Terraform such as Cycloid inventory overview, InfraPolicy and so on. Using Cycloid inventory, Terraform remote state files are sent to Cycloid API and stored in any of the compatible object storages such as Aws S3 bucket, Google Cloud Storage...

In the following graph you can have an overview of how the Cycloid Terraform HTTP backend works.

![Inventory-schema](/assets/images/inventory-schema-462abca59dc23d1b5f63f6d1cdba2992.png)

The following section explains how to use Cycloid inventory in both Cycloid pipelines and directly in Terraform code.

### How to use it in a pipelines ?[​](#how-to-use-it-in-a-pipelines- "Direct link to How to use it in a pipelines ?")

In a pipeline template simply start by defining the Terraform resource type and then configuring a terraform resource with Cycloid HTTP backend by using the option `backend_config`

```
resource_types:
- name: terraform
  type: registry-image
  source:
    repository: cycloid/terraform-resource

resources:
- name: tfstate
  type: terraform
  icon: terraform
  source:
    backend_config:
      address: '($ cycloid_api_url $)/inventory?jwt=($ inventory_jwt $)'
      ## skip_cert_verification needs to be enabled when using self signed certificates.
      # skip_cert_verification: true
    backend_type: http
    env_name: default
    vars:
      env: ((env))
      project: ((project))
      customer: ((customer))
```

where `cycloid_api_url` a pipeline variable containing the Cycloid API url (ex `https://http-api.cycloid.io` on our Saas). And `($ inventory_jwt $)` is a [Cycloid special variable](/reference/stacks/concepts/templating.md#special-variables) containing the jwt token of the Terraform HTTP backend.

This code sample uses our official `cycloid/terraform-resource` Docker image.

* Source code: [github.com/cycloidio/terraform-resource](https://github.com/cycloidio/terraform-resource)
* Docker image: [hub.docker.com/r/cycloid/terraform-resource](https://hub.docker.com/r/cycloid/terraform-resource)

A common mistake if you are editing an existing pipeline, is to use the wrong resource Docker image. Please make sure the **terraform** `resource_types` used is the Cycloid docker image `cycloid/terraform-resource`.

For more examples on how to use and configure Terraform in Cycloid pipelines, please refer to [Cycloid pipelines-examples section](/reference/ci-cd-pipelines/concepts/tools-integration/terraform.md)

### How to migrating an existing project ?[​](#how-to-migrating-an-existing-project- "Direct link to How to migrating an existing project ?")

The first step is to gather the current Terraform remote state configuration in your running pipeline. The 3 information you will need for the following step are:

* Credential: Name of the Cycloid credential used to access to your object storage.
* Object storage (bucket) name: The name of the bucket which contain the current tfstate file.
* tfstate path (key): The path where is located the tfstate file in the bucket.

You should be able to get those information by editing pipeline configuration or template, looking under the `resources` section for a `terraform` resources usually `tfstate`.

Example

* Amazon Web Services
* Google Cloud Platform
* Azure

```
resources:
  - name: tfstate
    type: terraform
    source:
      backend_config:
        access_key: ((aws.access_key))
        bucket: cycloid-terraform-remote-state
        key: myinfra-prod.tfstate
        region: eu-west-1
        secret_key: ((aws.secret_key))
        workspace_key_prefix: myinfra
      backend_type: s3
      env_name: prod
      vars:
        ...
```

* Credential: `aws`
* Object storage (bucket) name: `cycloid-terraform-remote-state`
* tfstate path (key): `{workspace_key_prefix}/{env_name}/{key}` -> `myinfra/prod/myinfra-prod.tfstate`

See Terraform backend doc [here](https://developer.hashicorp.com/terraform/language/backend/s3)

```
resources:
- name: tfstate
  type: terraform
  icon: terraform
  source:
    env_name: prod
    backend_type: gcs
    backend_config:
      bucket: cycloid-terraform-remote-state
      prefix: myinfra-prod/prod
      credentials: ((gcp-serviceaccount.json_key))
    vars:
      ...
```

* Credential: `gcp-serviceaccount`
* Object storage (bucket) name: `cycloid-terraform-remote-state`
* tfstate path (key): `{prefix}/{env_name}.tfstate` -> `myinfra-prod/prod/prod.tfstate`

See Terraform backend doc [here](https://developer.hashicorp.com/terraform/language/backend/gcs)

```
resources:
- name: tfstate
  type: terraform
  icon: terraform
  source:
    env_name: prod
    backend_type: azurerm
    backend_config:
      container_name: cycloidtstate
      key: myinfra/prod/myinfra-prod.tfstate
      storage_account_name: ((azure_storage_cycloidtfstate.account_name))
      access_key: ((azure_storage_cycloidtfstate.access_key))
    vars:
      ...
```

* Credential: `azure_storage_cycloidtfstate`
* Object storage (container): `cycloidtstate`
* tfstate path (key): `myinfra/prod/myinfra-prod.tfstate`

See Terraform backend doc [here](https://developer.hashicorp.com/terraform/language/backend/azurerm)

The second step is to configure if not already present a **remote Terraform backend** on your project. In your **project**, go under **configuration** tab and click on `Add configuration` button.

![Remote Terraform backend](/assets/images/project-terraform-be-018b2ba0f67d43910be0c6ef8924cfac.png)

Configure the remote Terraform backend using the information gathered previously.

warning

Ensure the `Object` field match the **tfstate path** defined earlier

Then hit the `Save` button. It will generate a dedicated Cycloid API JWT token known as `inventory_jwt` to use this newly created Terraform HTTP backend.

From this point, edit your pipeline following the [How to use Cycloid HTTP backend in Cycloid pipelines](/reference/inventory/concepts.md#how-to-use-it-in-a-pipelines-) section. And refresh your running pipelines.

### How to Use Cycloid HTTP Backend in Local Terraform Code[​](#how-to-use-cycloid-http-backend-in-local-terraform-code "Direct link to How to Use Cycloid HTTP Backend in Local Terraform Code")

While utilizing the pipeline is the preferred method for employing the HTTP backend, there may be scenarios where you need to run local Terraform code using the Cycloid HTTP backend for debugging purposes. Here's how you can achieve this:

In your local Terraform code, define a remote state backend in a file such as `backend.tmp.tf`:

```
terraform {
  backend "http" {
    address = "<CYCLOID_API_URL>/inventory?jwt=<JWT_TOKEN>"
    // skip_cert_verification needs to be enabled when using self signed certificates.
    // skip_cert_verification = true
  }
}
```

Ensure to substitute the following placeholders with appropriate values:

* `<CYCLOID_API_URL>`: Replace this with the Cycloid URL, for example, `https://http-api.cycloid.io` for the Cycloid SaaS version.
* `<JWT_TOKEN>`: Use the Cycloid HTTP backend token, which can be found under your project configuration tab.

If you're interested in exploring additional Terraform options for HTTP backends, refer to the official documentation [here](https://developer.hashicorp.com/terraform/language/backend/http).

This setup allows you to leverage the benefits of the Cycloid HTTP backend even when working with local Terraform code for debugging purposes.

### How manually upload tfstate file using our API[​](#how-manually-upload-tfstate-file-using-our-api "Direct link to How manually upload tfstate file using our API")

For troubleshooting or in edge cases, you may find it necessary to manually upload a tfstate file into the asset inventory, without running Terraform. Here's an example scenario:

Consider a situation where servers have been created manually, and their information is stored in a database. To export this information as Cycloid resources, you can develop a script to generate a file using the tfstate format. (It's important to note that tfstate files are in JSON format.) With this generated tfstate file, you can use our API to create and manage servers as resources within the Cycloid inventory.

This approach allows you to integrate existing infrastructure or manually managed resources into the Cycloid ecosystem, enabling centralized management and visibility.

To achieve this, follow the steps below:

```
export JWT_TOKEN="<JWT_TOKEN>"
export API_URL="<CYCLOID_API_URL>"

curl "${API_URL}/inventory?jwt=${JWT_TOKEN}" -X POST -H 'content-type: application/json' -d @/path/to/the/tfstate/file -v
```

where:

* `<JWT_TOKEN>`: Use the Cycloid HTTP backend token, which can be found under your project configuration tab.
* `<CYCLOID_API_URL>`: Replace this with the Cycloid URL, for example, `https://http-api.cycloid.io` for the Cycloid SaaS version.

## Custom Resources[​](#custom-resources "Direct link to Custom Resources")

An alternative method for adding resources to the asset inventory involves manually adding them through the Cycloid dashboard or via API calls.

**Using the Dashboard:** Adding resources via the dashboard is straightforward. Click the **Add resource** button and complete the form as shown below:

![inventory-manual-resource](/assets/images/inventory-manual-resource-64d172949c1c31bfb417d16376b51647.png)

You can include as many custom attributes as needed.

**Using the API:** Resources can be created and deleted through API calls. Below are examples of how to do this:

**Create**:

```
export API_KEY="<API_KEY>"
export API_URL="<CYCLOID_API_URL>"
export CY_ORG="<CYCLOID_ORGANIZATION>"

curl "${API_URL}/organizations/${CY_ORG}/inventory/resources" \
-H "authorization: Bearer $API_KEY" \
-H 'content-type: application/vnd.cycloid.io.v1+json' \
--data-raw '{
                    "name": "server1",
                    "provider": "custom_resources",
                    "label": "doc-project",
                    "type": "Server",
                    "memory": 1024,
                    "storage": 10240,
                    "cpu": 1,
                    "custom_attributes": {
                        "env": "doc"
                    }
                }'
```

* `<API_KEY>`: Your Cycloid API key.
* `<CYCLOID_API_URL>`: The URL for your Cycloid instance, for example, `https://http-api.cycloid.io` for the Cycloid SaaS version.
* `<CYCLOID_ORGANIZATION>`: The canonical name of the Cycloid organization associated with the API key.

**List**:

```
curl "${API_URL}/organizations/${CY_ORG}/inventory" \
-H "authorization: Bearer $API_KEY" \
-H 'content-type: application/vnd.cycloid.io.v1+json'
```

**Update**:

```
export RESOURCE_ID="<RESOURCE_ID>"
curl "${API_URL}/organizations/${CY_ORG}/inventory/resources/${RESOURCE_ID}" \
-H "authorization: Bearer $API_KEY" \
-H 'content-type: application/vnd.cycloid.io.v1+json' \
-X 'PUT' \
--data-raw '{
                "name": "server1",
                "provider": "custom_resources",
                "label": "example-project",
                "type": "Server",
                "memory": 0,
                "storage": 0,
                "cpu": 0,
                "custom_attributes": {
                    "env": "example"
                }
            }'
```

* `<RESOURCE_ID>`: The ID of the resource you want to update.

**Delete**:

```
export RESOURCE_ID="<RESOURCE_ID>"
curl "${API_URL}/organizations/${CY_ORG}/inventory/resources/${RESOURCE_ID}" \
-H "authorization: Bearer $API_KEY" \
-H 'content-type: application/vnd.cycloid.io.v1+json' \
-X 'DELETE'
```

* `<RESOURCE_ID>`: The ID of the resource you want to delete.


---

# Reference

## Use Cycloid Terraform HTTP backend in a pipeline[​](#use-cycloid-terraform-http-backend-in-a-pipeline "Direct link to Use Cycloid Terraform HTTP backend in a pipeline")

<!-- -->

In a pipeline template simply start by defining the Terraform resource type and then configuring a terraform resource with Cycloid HTTP backend by using the option `backend_config`

```
resource_types:
- name: terraform
  type: registry-image
  source:
    repository: cycloid/terraform-resource

resources:
- name: tfstate
  type: terraform
  icon: terraform
  source:
    backend_config:
      address: '($ cycloid_api_url $)/inventory?jwt=($ inventory_jwt $)'
      ## skip_cert_verification needs to be enabled when using self signed certificates.
      # skip_cert_verification: true
    backend_type: http
    env_name: default
    vars:
      env: ((env))
      project: ((project))
      customer: ((customer))
```

where `cycloid_api_url` a pipeline variable containing the Cycloid API url (ex `https://http-api.cycloid.io` on our Saas). And `($ inventory_jwt $)` is a [Cycloid special variable](/reference/stacks/concepts/templating.md#special-variables) containing the jwt token of the Terraform HTTP backend.


---

# legacy docs

This section contains legacy docs we saved and are going to migrate


---

# Create my first Stack

This guide covers how to create your own Cycloid private stack from scratch. The source code for each step in the documentation is available [here](https://github.com/cycloid-community-catalog/docs-step-by-step-stack).

We will create a stack called `stack-sample` to create & deploy a cloud instance using Terraform and a pipeline.

Here is an overview of the final result: ![Final pipeline](/assets/images/full_pipeline-f795dee5f7240d426fe38f24238e326d.png)

This pipeline will get the source code of a website from a Git repository, run unit tests on the code, and then create and deploy a cloud instance to run the website using this code with Terraform.


---

# Prepare Cycloid credentials

Let's create Cycloid credentials that we will use in our pipeline. Click on **Credentials** under **Security** in the left menu.

![menu\_creds](data:image/png;base64,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)

**1. SSH key**: Add a new credential named `ssh_key` of type `ssh`. Put your private SSH key in the `ssh_key` field.

This creates an SSH credential under the path `ssh_key`, which will be used to interact with the Git repository.

* Amazon Web Services
* Microsoft Azure
* Google Cloud Platform

**2. AWS access key**: Create a second credential of type `aws` named `aws_step-by-step` too.

This creates an AWS credential under the path `aws_step-by-step`, which will be used to interact with AWS.

![Cycloid AWS credentials](/assets/images/aws-step-by-step-creds-f96644246702be68fa4aa81d17bc9a50.jpg)

**2. Azure storage**: Create a second credential of type `azure_storage` named `azure_storage_step-by-step` too.

This creates an Azure storage credential under the path `azure_storage_step-by-step`, which will be used to interact with Azure storage.

![Cycloid Azure Storage credentials](/assets/images/azure-storage-step-by-step-creds-04343e41480d7b7949051c70d04eab3a.jpg)

**3. Azure credential**: Create a third credential of type `azure` named `azure_step-by-step` too.

This creates an Azure credential under the path `azure_step-by-step`, which will be used to interact with Azure.

![Cycloid Azure credentials](/assets/images/azure-step-by-step-creds-3b2381bb686cd1629e4337ea9fc5c93d.jpg)

**2. GCP service account key**: Create a second credential of type `gcp` named `gcp_step-by-step` too.

This creates a GCP credential under the path `gcp_step-by-step`, which will be used to interact with GCP.

![Cycloid GCP credentials](/assets/images/gcp-step-by-step-creds-346d8d5072800c49f9c4c9e42e6c0664.jpg)


---

# Requirements

To simplify the step by step guide, we assume that you provide the following elements:

* An empty **Git repository** *(you can use Github, Bitbucket, Gitlab, AWS CodeCommit, etc.)*:

  <!-- -->

  * Later on, we will create two branches (`stacks` and `config`)
  * SSH key to access to the repository

- Amazon Web Services
- Microsoft Azure
- Google Cloud Platform

* An empty [**AWS S3 buckets**](https://docs.aws.amazon.com/quickstarts/latest/s3backup/step-1-create-bucket.html). We recommend to enable **versioning**:
  <!-- -->
  * `($ organization_canonical $)-terraform-remote-state`: Store [Terraform remote state file](https://www.terraform.io/language/state/remote)

* **Amazon access key**:

  <!-- -->

  * Require permissions to create and execute a AWS EC2 instance
  * Also require read and write permissions on the previous S3 bucket

- An empty [**Azure blob storage and an Azure blob container**](https://docs.microsoft.com/en-us/azure/storage/blobs/storage-blobs-introduction)

  * Storage: `($ organization_canonical $)tfstate` *(make sure you respect the Azure storage name restrictions)*
  * Container: `($ organization_canonical $)`

- **Azure** [credentials](https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs#authenticating-to-azure)
  * `client_id`, `subscription_id`, `tenant_id`, ...

- A subnet id from an [Azure virtual network/subnet](https://docs.microsoft.com/en-us/azure/virtual-network/quick-create-portal) on which we will be able to create a VM with internet access to download the website source code

* An empty [**GCP object storage bucket**](https://cloud.google.com/storage/docs/creating-buckets):
  <!-- -->
  * `($ organization_canonical $)-terraform-remote-state`: Store [Terraform remote state file](https://www.terraform.io/language/state/remote)

* [**GCP service account key**](https://cloud.google.com/iam/docs/creating-managing-service-accounts):

  <!-- -->

  * Require permissions to create and execute a GCP compute instance
  * Also require read and write permissions on the previous object storage bucket

Important

In this guide, we use and create two branches into the same git repository to keep things simple. But when you build your own stack, it's up to you to define if you want to use one unique branch, several branches, or even split them across different git repositories.


---

# Application source code

In this guide, we will deploy an HTML website on a cloud instance.

To make it easier, we published a basic website source code in our public Git repository.

![Website](/assets/images/website-2ec56a28e6a7efe5909dadb21606d3d6.png)

If you are a new user of Cycloid, we recommend you follow the guide using our website source git repository. By default, this guide is configured to use our [git repository](https://github.com/cycloid-community-catalog/docs-step-by-step-stack/tree/code).


---

# Initiate a `stacks` branch with a basic pipeline

* Amazon Web Services
* Microsoft Azure
* Google Cloud Platform

- Check out the `git diff` of this step [here](https://github.com/cycloid-community-catalog/docs-step-by-step-stack/commit/Step2-aws).

* Check out the `git diff` of this step [here](https://github.com/cycloid-community-catalog/docs-step-by-step-stack/commit/Step2-azure).

- Check out the `git diff` of this step [here](https://github.com/cycloid-community-catalog/docs-step-by-step-stack/commit/Step2-gcp).

![Pipeline step2](/assets/images/pipeline-step2-572f992f2267018ef9dfa62fca5fe218.png)

As described in [Concepts of a stack](/reference/stacks/concepts/stack-concept.md), we start by creating a stack. Create a `stacks` branch containing our stack directory that we will call `stack-sample` and put a hello world pipeline template in it. Then add a description of our stack in a [.cycloid.yml](/reference/stacks/reference/cycloid-file.md) file.

Follow those steps to apply all changes described in this step

* Amazon Web Services
* Microsoft Azure
* Google Cloud Platform

```
git checkout --orphan stacks
git rm -rf .
mkdir -p stack-sample/pipeline

wget -O stack-sample/.cycloid.yml https://raw.githubusercontent.com/cycloid-community-catalog/docs-step-by-step-stack/Step2-aws/stack-sample/.cycloid.yml
wget -O stack-sample/README.md https://raw.githubusercontent.com/cycloid-community-catalog/docs-step-by-step-stack/Step2-aws/stack-sample/README.md
wget -O stack-sample/pipeline/variables.sample.yml https://raw.githubusercontent.com/cycloid-community-catalog/docs-step-by-step-stack/Step2-aws/stack-sample/pipeline/variables.sample.yml
wget -O stack-sample/pipeline/pipeline.yml https://raw.githubusercontent.com/cycloid-community-catalog/docs-step-by-step-stack/Step2-aws/stack-sample/pipeline/pipeline.yml

git add .
git commit -m "Step 2"
git push origin stacks
```

```
git checkout --orphan stacks
git rm -rf .
mkdir -p stack-sample/pipeline

wget -O stack-sample/.cycloid.yml https://raw.githubusercontent.com/cycloid-community-catalog/docs-step-by-step-stack/Step2-azure/stack-sample/.cycloid.yml
wget -O stack-sample/README.md https://raw.githubusercontent.com/cycloid-community-catalog/docs-step-by-step-stack/Step2-azure/stack-sample/README.md
wget -O stack-sample/pipeline/variables.sample.yml https://raw.githubusercontent.com/cycloid-community-catalog/docs-step-by-step-stack/Step2-azure/stack-sample/pipeline/variables.sample.yml
wget -O stack-sample/pipeline/pipeline.yml https://raw.githubusercontent.com/cycloid-community-catalog/docs-step-by-step-stack/Step2-azure/stack-sample/pipeline/pipeline.yml

git add .
git commit -m "Step 2"
git push origin stacks
```

```
git checkout --orphan stacks
git rm -rf .
mkdir -p stack-sample/pipeline

wget -O stack-sample/.cycloid.yml https://raw.githubusercontent.com/cycloid-community-catalog/docs-step-by-step-stack/Step2-gcp/stack-sample/.cycloid.yml
wget -O stack-sample/README.md https://raw.githubusercontent.com/cycloid-community-catalog/docs-step-by-step-stack/Step2-gcp/stack-sample/README.md
wget -O stack-sample/pipeline/variables.sample.yml https://raw.githubusercontent.com/cycloid-community-catalog/docs-step-by-step-stack/Step2-gcp/stack-sample/pipeline/variables.sample.yml
wget -O stack-sample/pipeline/pipeline.yml https://raw.githubusercontent.com/cycloid-community-catalog/docs-step-by-step-stack/Step2-gcp/stack-sample/pipeline/pipeline.yml

git add .
git commit -m "Step 2"
git push origin stacks
```

### Cycloid.yml[​](#cycloidyml "Direct link to Cycloid.yml")

Each stack has to contain a [.cycloid.yml](/reference/stacks/reference/cycloid-file.md) file, which describes global information about a stack such as a name, the icon, ansible/terraform paths, etc.

### Readme.md (optional)[​](#readmemd-optional "Direct link to Readme.md (optional)")

To provide detailed information and documentation about your stack (goal, requirements, usage), you can add a [README.md](/reference/stacks/concepts/stack-definition.md) file in Markdown format. The content of this file will be visible by the users in the Cycloid console as part of the stack details page.

Having a README will display detailed information about your stack for others to understand what it is about.

### Pipeline[​](#pipeline "Direct link to Pipeline")

A pipeline is composed of 2 files. A pipeline template file (`pipeline.yml`) and an example of variables file (`variables.sample.yml`) used for the templating using the `((variable_name))` format.

*stack-sample/pipeline/pipeline.yml*

```
groups:
- name: overview
  jobs:
  - unittest

resources:

- name: git_code
  type: git
  source:
    uri: ((code_git_public_repository))
    branch: ((code_git_branch))

jobs:
  - name: unittest
    max_in_flight: 1
    build_logs_to_retain: 10
    plan:
    - do:
      - get: git_code
        trigger: true
      - task: test
        config:
          platform: linux
          image_resource:
            type: registry-image
            source:
              repository: cycloid/cycloid-toolkit
              tag: latest
          run:
            path: /bin/bash
            args:
            - -ec
            - |
              echo "Testing the application"
              ls code
          inputs:
          - name: git_code
            path: code
```

Due to the CI/CD solution named [Concourse](https://concourse-ci.org/) and used by Cycloid for running pipelines, it's essential to know that a pipeline results from configuring **Jobs** and **Resources** together.

In our example, we defined a resource of type `git` named `git_code` and a job named `unittest`. Each **job** have to be part of a `group`, it will create a group view on Cycloid console to display pipeline jobs.

**git\_code**: is a [resource](https://concourse-ci.org/resources.html) to define a Git repository. This resource will trigger the job to test the code when the repository is updated.

**unittest**: is a [job](https://concourse-ci.org/jobs.html). It describes the steps needed to complete a job. In our case we need to get our website source code, then run tests. The usual steps are:

* `get` step: Fetches a resource, making it available to subsequent tasks via the given name.
* `put` step: Pushes to the given resource. For example, for the git resource, a push would `git commit/push` into the repository.
* `task` step: Executes a Task with inline configuration.

tip

Resources and tasks are based on Docker images. It's really flexible and allows you to provide your own environment or required tools. If you are interested in implementing your own resource, please follow <https://concourse-ci.org/implementing-resource-types.html> documentation.

This `unittest` job `get` the source code of our website using the `git_code` resource *(see line 20)*, then runs a `task` to test our website source code. *(line 22)*. This test actually just lists files but you usually should put the real commands to test your application source code.

warning

`inputs` and `outputs` are volumes exposed to/from a task with others steps. In our case, we say that our task requires the content of the `git_code` resource as `input` in the directory `code`.

If you want to know more about pipelines, you can read our [Pipeline guide](/reference/ci-cd-pipelines/concepts/pipelines-overview.md) and the [Concourse](https://concourse-ci.org/pipelines.html) documentation.

### Variables sample[​](#variables-sample "Direct link to Variables sample")

The variables sample file is used as an example when you create a project using Cycloid's dashboard.

*stack-sample/pipeline/variables.sample.yml*

```
env: ($ environment $)
project: ($ project $)
customer: ($ organization_canonical $)

# Code repo configuration
code_git_public_repository: https://github.com/cycloid-community-catalog/docs-step-by-step-stack.git
code_git_branch: code
```

The format of this file is pretty simple, `key: value`. But there are 2 specificities:

* **The first 3 lines** are [Cycloid special variables](/reference/stacks/concepts/templating.md) automatically provided when you create a project.
* **Line 6** contains a regular string variable, in our case the URL of the git repository to use for our website source code.

***

### Key points to remember[​](#key-points-to-remember "Direct link to Key points to remember")

* Each stack has to contain a [.cycloid.yml](/reference/stacks/reference/cycloid-file.md) file
* To provide detailed information and documentation about your stack (goal, requirements, usage), you can add a [README.md](/reference/stacks/concepts/stack-definition.md) file in Markdown format
* A pipeline is composed of 2 files. A pipeline template file (`pipeline.yml`) and an example of variables file (`variables.sample.yml`) used for the templating using the `((variable_name))` format
* The variables sample file is used as an example when you create a project using Cycloid's dashboard
* A pipeline contain Jobs and Resources


---

# Step 2 part 2 - Use a stack

### Create a config branch in your git repository[​](#create-a-config-branch-in-your-git-repository "Direct link to Create a config branch in your git repository")

Creating a config branch in your git repository will be explained in detail later in this guide.

For now, we will initialize an empty git branch named `config` to be able to create a **Config repository**

```
git checkout --orphan config
git rm -rf .
touch .gitignore
git add .gitignore
git commit -m "Init config branch"
git push origin config
git checkout stacks
```

Then, you need to add a [Config repository](/reference/config-and-catalog-repository/.md) on Cycloid. To match the default sample value, please use

* `step-by-step-cr` as name
* `your git repository SSH URL` as URL
* `ssh_key` as credential
* `config` as branch

![Private config repository](/assets/images/config-2f440e38169a6df871f02e87eafd0189.png)

### Create a project with a private catalog[​](#create-a-project-with-a-private-catalog "Direct link to Create a project with a private catalog")

Previously, we created a stack in a `stacks` branch of your private git repository. Now we will see how to define it on the Cycloid console to create a project from it in your organization.

Start to add a private catalog repository following the [Catalog repository](/reference/config-and-catalog-repository/.md) documentation. To match the default sample value, please use

* `step-by-step` as name
* `your git repository SSH URL` as URL
* `ssh_key` as credential
* `stack` as branch

![Private catalog repository](/assets/images/catalog-df93da2f41a7bd638e1415f5ab7233ae.png)

After configuring the private service catalog, let's create a new project called **Snowy** with a **Test** environment.

1. Go on Cycloid's dashboard and click on `Projects` / `Create a new project`

2. Enter the name **Snowy** and select the **Config repository** you created earlier

![Project creation](/assets/images/project-creation-7335895707dc56c041d69eb66e836da0.png)

3. Your new private stack should be available in the stack list by looking for `stack-sample` keyword, select it by clicking on **Use this stack**

![Stack](/assets/images/stack-24f3361316c9fdb0507d3b8e41045ddd.png)

4. You now have the choice to create an environment. Specify the **Test** environment and click **Next**

![Environment creation](/assets/images/env-creation-0846709035de2c3821e3fdfcc1dd8736.png)

5. The wizard should now display the pipeline and the variables to use from the `variables.sample.yml` file. Configure those variables with your own values

![Create project](/assets/images/create-project-812c085993125d82dc2aa1828432bcae.png)

6. Move on to the last step of the wizard and click on the `Run` button

![Run project](/assets/images/run-project-5b02ac8cc8768514b2434e70816f4c5a.png)

Congrats! You created a project using your own stack. In the next steps, we will go a little bit further to improve the pipeline by adding jobs.

***

### Key points to remember[​](#key-points-to-remember "Direct link to Key points to remember")

* To create a Cycloid project you must first create a [Config repository](/reference/config-and-catalog-repository/.md)
* To use a private stack on a Cycloid project, you need to create a private [Catalog repository](/reference/config-and-catalog-repository/.md), which contains your stack
* You need to create at least one environment to finalize the creation of a Cycloid project


---

# Configure the pipeline to run Terraform plan

* Amazon Web Services
* Microsoft Azure
* Google Cloud Platform

- Check out the `git diff` of this step [here](https://github.com/cycloid-community-catalog/docs-step-by-step-stack/commit/Step3-aws).

* Check out the `git diff` of this step [here](https://github.com/cycloid-community-catalog/docs-step-by-step-stack/commit/Step3-azure).

- Check out the `git diff` of this step [here](https://github.com/cycloid-community-catalog/docs-step-by-step-stack/commit/Step3-gcp).

![Pipeline step3](/assets/images/pipeline-step3-145ed7dae36bfbe825fd185ae564b15e.png)

To complete this step, we will use what we previously saw in **Step 2** by adding a new job to run Terraform if our `unittest` job succeed. The goal is to configure a new resource to run Terraform and use it in a dedicated job.

Additionally to that, the Terraform code will be stored in your Git repository, inside the `stacks` branch. This means we will also configure a `git` resource in the pipeline to `get` the content of the `stacks` branch.

Follow those steps to apply all changes described in this step

* Amazon Web Services
* Microsoft Azure
* Google Cloud Platform

```
export GIT_REPO=$(git remote get-url origin)
mkdir stack-sample/terraform
wget -O stack-sample/terraform/provider.tf https://raw.githubusercontent.com/cycloid-community-catalog/docs-step-by-step-stack/Step3-aws/stack-sample/terraform/provider.tf
wget -O stack-sample/pipeline/pipeline.yml https://raw.githubusercontent.com/cycloid-community-catalog/docs-step-by-step-stack/Step3-aws/stack-sample/pipeline/pipeline.yml
wget -O stack-sample/pipeline/variables.sample.yml https://raw.githubusercontent.com/cycloid-community-catalog/docs-step-by-step-stack/Step3-aws/stack-sample/pipeline/variables.sample.yml
sed -i "s#git@github.com:cycloid-community-catalog/docs-step-by-step-stack.git#$GIT_REPO#" stack-sample/pipeline/variables.sample.yml
```

```
# Azure configuration, make sure to replace the following variable content regarding your own Azure account configuration
export AZURE_RESOURCE_GROUP_NAME=cycloid-demo
export AZURE_LOCATION=francecentral
export AZURE_ENV=public
export TERRAFORM_STORAGE_CONTAINER_NAME=cycloid-demo

export GIT_REPO=$(git remote get-url origin)
mkdir stack-sample/terraform
wget -O stack-sample/terraform/provider.tf https://raw.githubusercontent.com/cycloid-community-catalog/docs-step-by-step-stack/Step3-azure/stack-sample/terraform/provider.tf
wget -O stack-sample/pipeline/pipeline.yml https://raw.githubusercontent.com/cycloid-community-catalog/docs-step-by-step-stack/Step3-azure/stack-sample/pipeline/pipeline.yml
wget -O stack-sample/pipeline/variables.sample.yml https://raw.githubusercontent.com/cycloid-community-catalog/docs-step-by-step-stack/Step3-azure/stack-sample/pipeline/variables.sample.yml
sed -i "s#git@github.com:cycloid-community-catalog/docs-step-by-step-stack.git#$GIT_REPO#" stack-sample/pipeline/variables.sample.yml
sed -i "s/azure_resource_group_name:.*/azure_resource_group_name: $AZURE_RESOURCE_GROUP_NAME/g" stack-sample/pipeline/variables.sample.yml
sed -i "s/azure_location:.*/azure_location: $AZURE_LOCATION/g" stack-sample/pipeline/variables.sample.yml
sed -i "s/azure_env:.*/azure_env: $AZURE_ENV/g" stack-sample/pipeline/variables.sample.yml
sed -i "s/terraform_storage_container_name:.*/terraform_storage_container_name: $TERRAFORM_STORAGE_CONTAINER_NAME/g" stack-sample/pipeline/variables.sample.yml
```

```
export GCP_PROJECT_NAME=my_gcp_project

export GIT_REPO=$(git remote get-url origin)
mkdir stack-sample/terraform
wget -O stack-sample/terraform/provider.tf https://raw.githubusercontent.com/cycloid-community-catalog/docs-step-by-step-stack/Step3-gcp/stack-sample/terraform/provider.tf
wget -O stack-sample/pipeline/pipeline.yml https://raw.githubusercontent.com/cycloid-community-catalog/docs-step-by-step-stack/Step3-gcp/stack-sample/pipeline/pipeline.yml
wget -O stack-sample/pipeline/variables.sample.yml https://raw.githubusercontent.com/cycloid-community-catalog/docs-step-by-step-stack/Step3-gcp/stack-sample/pipeline/variables.sample.yml
sed -i "s#git@github.com:cycloid-community-catalog/docs-step-by-step-stack.git#$GIT_REPO#" stack-sample/pipeline/variables.sample.yml
sed -i "s/gcp_project:.*/gcp_project: $GCP_PROJECT_NAME/" stack-sample/pipeline/variables.sample.yml
```

Starting with the Terraform code. Let's create a dummy Terraform configuration with the cloud provider we want to use for Terraform in a `provider.tf` file.

tip

If you are not comfortable with Terraform, we encourage you to follow [Terraform getting started](https://developer.hashicorp.com/terraform/tutorials/aws-get-started/install-cli) documentation.

The content of the `provider.tf` specifies the provider configuration ([GCP](https://registry.terraform.io/providers/hashicorp/google/latest/docs), [AWS](https://registry.terraform.io/providers/hashicorp/aws/latest/docs), [AzureRM](https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs)) and [variables](https://www.terraform.io/language/values/variables) to configure it. Those variables will be provided by the pipeline.

*stack-sample/terraform/provider.tf*

* Amazon Web Services
* Microsoft Azure
* Google Cloud Platform

```
variable "customer" {}
variable "project" {}
variable "env" {}

variable "git_code_commit" {
  default = "origin/code"
}
variable "git_code_repo" {
  default = "https://github.com/cycloid-community-catalog/docs-step-by-step-stack.git"
}

# Aws
provider "aws" {
  access_key = var.access_key
  secret_key = var.secret_key
  region     = var.aws_region
}
variable "access_key" {}
variable "secret_key" {}
variable "aws_region" {}
```

```
variable "customer" {}
variable "project" {}
variable "env" {}

# Azure
variable "azure_client_id" {}
variable "azure_client_secret" {}
variable "azure_subscription_id" {}
variable "azure_tenant_id" {}
variable "azure_env" {
  default = "public"
}
variable "azure_resource_group_name" {}
variable "azure_location" {
  default = "francecentral"
}

# Source code
variable "git_code_commit" {
  default = "origin/code"
}
variable "git_code_repo" {
  default = "https://github.com/cycloid-community-catalog/docs-step-by-step-stack.git"
}

# Azure
provider "azurerm" {
  version = "~> 1.42.0"

  environment     = var.azure_env
  client_id       = var.azure_client_id
  client_secret   = var.azure_client_secret
  subscription_id = var.azure_subscription_id
  tenant_id       = var.azure_tenant_id
}
```

```
variable "customer" {}
variable "project" {}
variable "env" {}

variable "git_code_commit" {
  default = "origin/code"
}
variable "git_code_repo" {
  default = "https://github.com/cycloid-community-catalog/docs-step-by-step-stack"
}

# GCP
provider "google" {
  version = "~> 2.18.0"
  project = var.gcp_project
}
variable "gcp_project" {
  default = "cycloid-demo"
}
variable "gcp_zone" {
  default = "europe-west1-b"
}
```

Several input variables have been defined to configure the cloud provider and two variables to pass the source code git repository URL that we will use and explain in the next step. The `provider.tf` usually also contain some generic variables like `customer`, `project` and `env` as most of our customer use them in Terraform to tag/name cloud resources.

Now add a Terraform resource into the pipeline. As Terraform is not part of the [core resources type](https://github.com/concourse/concourse/wiki/Resource-Types) of Concourse, the first thing is to specify a new `terraform` resource type in the dedicated root section `resource_types`.

tip

**When to use a task or a resource in a pipeline?**

In our case, we could have provided our container image with Terraform already installed on it and called the `terraform` command. A resource usually is here to simplify a task. It makes something more generic and easy to use with embedded scripts. A resource also creates versions that can be used between different jobs as triggers.

If you are interested in creating your own resource, follow the [Concourse](https://concourse-ci.org/implementing-resource-types.html) documentation.

*stack-sample/pipeline/pipeline.yml*

```
resource_types:
  - name: terraform
    type: registry-image
    source:
      repository: ljfranklin/terraform-resource
      tag: '0.12.24'
```

The source code of this resource can be found [here](https://github.com/ljfranklin/terraform-resource).

From there, a new `terraform` resource type is available and can be configured. The following sample configures a resource called `tfstate` of our new `terraform` type:

*stack-sample/pipeline/pipeline.yml*

* Amazon Web Services
* Microsoft Azure
* Google Cloud Platform

```
resources:
...
- name: tfstate
  type: terraform
  source:
    env_name: ((env))
    backend_type: s3
    backend_config:
      bucket: ((terraform_storage_bucket_name))
      key: terraform.tfstate
      workspace_key_prefix: ((project))
      region: ((aws_default_region))
      access_key: ((aws_access_key))
      secret_key: ((aws_secret_key))
    vars:
      access_key: ((aws_access_key))
      secret_key: ((aws_secret_key))
      aws_region: ((aws_default_region))
      env: ((env))
      project: ((project))
      customer: ((customer))
```

```
resources:
...
- name: tfstate
  type: terraform
  icon: terraform
  source:
    env_name: ((env))
    backend_type: azurerm
    backend_config:
      container_name: ((terraform_storage_container_name))
      key: ((terraform_storage_container_path))/((project))-((env)).tfstate
      resource_group_name: ((azure_resource_group_name))
      storage_account_name: ((terraform_storage_account_name))
      access_key: ((terraform_storage_access_key))
    vars:
      azure_resource_group_name: ((azure_resource_group_name))
      azure_location: ((azure_location))
      azure_env: ((azure_env))
      azure_client_id: ((azure_client_id))
      azure_client_secret: ((azure_client_secret))
      azure_subscription_id: ((azure_subscription_id))
      azure_tenant_id: ((azure_tenant_id))
      env: ((env))
      project: ((project))
      customer: ((customer))
```

```
- name: tfstate
  type: terraform
  icon: terraform
  source:
    env_name: ((env))
    backend_type: gcs
    backend_config:
      bucket: ((terraform_storage_bucket_name))
      prefix: ((project))/((env))
      credentials: ((gcp_credentials_json))
    vars:
      gcp_project: ((gcp_project))
      gcp_zone: ((gcp_zone))
      env: ((env))
      project: ((project))
      customer: ((customer))
    env:
      GOOGLE_PROJECT: ((gcp_project))
      GOOGLE_ZONE: ((gcp_zone))
      GOOGLE_CREDENTIALS: ((gcp_credentials_json))
```

**Some explanations:** Terraform stores the status of the infrastructure in a file called [tfstate](https://developer.hashicorp.com/terraform/language/state). This file can be stored in different backends. In this example, we decided to use our cloud provider object store as [backend type](https://developer.hashicorp.com/terraform/language/backend#available-backends) to store this file. The `backend_type` parameter defines this, then configured in the `backend_config` section, using pipeline variables defined below. Refer to the dedicated Terraform documentation to know more about your backend storage configuration.

The `vars` section defines a collection of [Terraform input variables](https://developer.hashicorp.com/terraform/tutorials/aws-get-started/aws-variables) provided by the pipeline. Variables are given by the pipeline to Terraform. The most common ones are the cloud provider credentials that we defined in `provider.tf` and the extra `customer/project/env` that we previously saw.

Small detour by `variables.sample.yml` file to add our new pipeline variables:

*stack-sample/pipeline/variables.sample.yml*

* Amazon Web Services
* Microsoft Azure
* Google Cloud Platform

```
git_ssh_key: ((ssh_key.ssh_key))

# Branch used to store the config of the stack
git_repository: git@github.com:cycloidio/my_git_repository.git
stack_git_branch: stacks

# Aws access to use inside the pipeline
aws_access_key: ((aws_step-by-step.access_key))
aws_secret_key: ((aws_step-by-step.secret_key))
aws_default_region: eu-west-1

# Terraform tfstate storage Configuration
terraform_storage_bucket_name: ($ organization_canonical $)-terraform-remote-state
terraform_storage_bucket_path: ($ project $)
```

```
git_ssh_key: ((ssh_key.ssh_key))

# Branch used to store the config of the stack
git_repository: git@github.com:cycloidio/my_git_repository.git
stack_git_branch: stacks

# Terraform tfstate storage Configuration
terraform_storage_container_path: ($ project $)/($ environment $)
terraform_storage_container_name: cycloid-demo
terraform_storage_access_key: ((azure_storage_step-by-step.access_key))
terraform_storage_account_name: ((azure_storage_step-by-step.account_name))

azure_resource_group_name: cycloid-demo
azure_location: francecentral
azure_env: public

azure_subscription_id: ((azure_step-by-step.subscription_id))
azure_tenant_id: ((azure_step-by-step.tenant_id))
azure_client_id: ((azure_step-by-step.client_id))
azure_client_secret: ((azure_step-by-step.client_secret))
```

```
git_ssh_key: ((ssh_key.ssh_key))

# Code repo configuration
code_git_public_repository: https://github.com/cycloid-community-catalog/docs-step-by-step-stack.git
code_git_branch: code

# Branch used to store the config of the stack
git_repository: git@github.com:cycloidio/my_git_repository.git
stack_git_branch: stacks

# Terraform tfstate storage Configuration
terraform_storage_bucket_name: ($ organization_canonical $)-terraform-remote-state
terraform_storage_bucket_path: ($ project $)

gcp_project: cycloid-demo
gcp_zone: "europe-west1-b"
gcp_credentials_json: ((gcp_step-by-step.json_key))
```

We added several variables related to our pipeline changes.

* **git**: to provide the SSH key to get Terraform code from your private git repository (`git_ssh_key`). As well as the branch and URL to use (`stack_git_branch`, `git_repository`)
* **cloud provider**: to configure the cloud provider access and Terraform tfstate file storage.

As you can see, the value of some variables has a specific format `((myvalue))`. For example, in **line 1**, the value of this pipeline variable will be provided by a Cycloid credential. The one you previously created in the section [prepare Cycloid credentials](/reference/legacy-doc/create-my-first-stack/prepare-cycloid-credentials.md). See [pipeline variable](/reference/stackforms/concepts/technologies.md#pipeline) documentation for more information to use Cycloid credentials into a pipeline.

Getting back on the pipeline file to configure a `git` resource to get the dummy Terraform source code from our `stacks` branch.

*stack-sample/pipeline/pipeline.yml*

```
resources:
...
- name: git_stack
  type: git
  source:
    uri: ((git_repository))
    branch: ((stack_git_branch))
    private_key: ((git_ssh_key))
    paths:
      - stack-sample/terraform/*
```

We also added a filter on Terraform path using `paths` to trigger terraform jobs only when commits change terraform files.

Standard pipeline behavior with Terraform is to run [Terraform plan](https://www.terraform.io/cli/commands/plan). It's a convenient way to check the execution plan for a set of changes that matches your expectations without making any changes to real resources. Then create a second job to apply those changes by calling [Terraform apply](https://www.terraform.io/cli/commands/apply).

Let's start and create the dedicated job to run `terraform plan` command just after `unittest` job (`passed` argument) and speak about `terraform apply` in the next step:

*stack-sample/pipeline/pipeline.yml*

```
jobs:
...
  - name: terraform-plan
    max_in_flight: 1
    build_logs_to_retain: 10
    plan:
      - do:
        - get: git_stack
          trigger: true
        - get: git_code
          trigger: true
          passed:
            - unittest
        - put: tfstate
          params:
            plan_only: true
            terraform_source: git_stack/stack-sample/terraform
```

An important point is the `passed` parameter that you can put on `get` action. This keyword links jobs together to ensure that we will get the code already processed by the `unittest` job.

This job gets Terraform code from `git_stack` resource, which is our git on the `stacks` branch. Then call [put](https://github.com/ljfranklin/terraform-resource#put-parameters) on Terraform resource (`tfstate`) using `plan_only` parameter to specify that we want only to run `terraform plan`.

Don't forget to add this job to a group:

*stack-sample/pipeline/pipeline.yml*

```
groups:
- name: overview
  jobs:
  - unittest
  - terraform-plan
```

Click on the `terraform-plan` job and see Terraform logs saying we successfully run it with 0 changes.

![Terraform](/assets/images/terraform-1-e0798275467080bdcec8b21a17652e90.png)

Add and commit those changes in **Git**:

```
git add .
git commit -m "Step 3"
git push origin stacks
```

Get back to Cycloid's dashboard, and click on the `Refresh pipeline` button ![Refresh pipeline](/assets/images/reset-pipeline-47a7ea6c1da66e9e2da26f926a41a6fd.png).

***

### Key points to remember[​](#key-points-to-remember "Direct link to Key points to remember")

* As Terraform is not part of the [core resources type](https://github.com/concourse/concourse/wiki/Resource-Types) of Concourse, the first thing is to specify a new `terraform` resource type in the dedicated root section `resource_types`
* Terraform stores the status of the infrastructure in a file called [tfstate](https://developer.hashicorp.com/terraform/language/state). This file can be stored in different backends
* Standard pipeline behavior with Terraform is to run [Terraform plan](https://www.terraform.io/cli/commands/plan) then [Terraform apply](https://www.terraform.io/cli/commands/apply)


---

# Create a Terraform module and add Terraform apply job in the pipeline

* Amazon Web Services
* Microsoft Azure
* Google Cloud Platform

- Check out the `git diff` of this step [here](https://github.com/cycloid-community-catalog/docs-step-by-step-stack/commit/Step4-aws).

* Check out the `git diff` of this step [here](https://github.com/cycloid-community-catalog/docs-step-by-step-stack/commit/Step4-azure).

- Check out the `git diff` of this step [here](https://github.com/cycloid-community-catalog/docs-step-by-step-stack/commit/Step4-gcp).

![Pipeline step4](/assets/images/pipeline-step4-34983d3141b91474bcbd9c3be25e4d95.png)

Terraform plan job is now configured and working. It's time to push some real Terraform codes to describe a cloud instance using [Terraform module format](https://www.terraform.io/language/modules/syntax).

Follow those steps to apply all changes described in this step

* Amazon Web Services
* Microsoft Azure
* Google Cloud Platform

```
mkdir stack-sample/terraform/module-aws

wget -O stack-sample/terraform/outputs.tf https://raw.githubusercontent.com/cycloid-community-catalog/docs-step-by-step-stack/Step4-aws/stack-sample/terraform/outputs.tf
wget -O stack-sample/terraform/main.tf https://raw.githubusercontent.com/cycloid-community-catalog/docs-step-by-step-stack/Step4-aws/stack-sample/terraform/main.tf
wget -O stack-sample/terraform/module-aws/ami.tf https://raw.githubusercontent.com/cycloid-community-catalog/docs-step-by-step-stack/Step4-aws/stack-sample/terraform/module-aws/ami.tf
wget -O stack-sample/terraform/module-aws/outputs.tf https://raw.githubusercontent.com/cycloid-community-catalog/docs-step-by-step-stack/Step4-aws/stack-sample/terraform/module-aws/outputs.tf
wget -O stack-sample/terraform/module-aws/userdata.sh.tpl https://raw.githubusercontent.com/cycloid-community-catalog/docs-step-by-step-stack/Step4-aws/stack-sample/terraform/module-aws/userdata.sh.tpl
wget -O stack-sample/terraform/module-aws/variables.tf https://raw.githubusercontent.com/cycloid-community-catalog/docs-step-by-step-stack/Step4-aws/stack-sample/terraform/module-aws/variables.tf
wget -O stack-sample/terraform/module-aws/vm.tf https://raw.githubusercontent.com/cycloid-community-catalog/docs-step-by-step-stack/Step4-aws/stack-sample/terraform/module-aws/vm.tf
wget -O stack-sample/pipeline/pipeline.yml https://raw.githubusercontent.com/cycloid-community-catalog/docs-step-by-step-stack/Step4-aws/stack-sample/pipeline/pipeline.yml
```

```
# Azure requirement
# Put your azure subnet ID here. It should looks like "/subscriptions/.../resourceGroups/cycloid-demo/providers/Microsoft.Network/virtualNetworks/default/subnets/default"
export AZURE_SUBNET="<your azure subnet id>"

mkdir stack-sample/terraform/module-azure

wget -O stack-sample/terraform/outputs.tf https://raw.githubusercontent.com/cycloid-community-catalog/docs-step-by-step-stack/Step4-azure/stack-sample/terraform/outputs.tf
wget -O stack-sample/terraform/main.tf https://raw.githubusercontent.com/cycloid-community-catalog/docs-step-by-step-stack/Step4-azure/stack-sample/terraform/main.tf
wget -O stack-sample/terraform/module-azure/outputs.tf https://raw.githubusercontent.com/cycloid-community-catalog/docs-step-by-step-stack/Step4-azure/stack-sample/terraform/module-azure/outputs.tf
wget -O stack-sample/terraform/module-azure/userdata.sh.tpl https://raw.githubusercontent.com/cycloid-community-catalog/docs-step-by-step-stack/Step4-azure/stack-sample/terraform/module-azure/userdata.sh.tpl
wget -O stack-sample/terraform/module-azure/variables.tf https://raw.githubusercontent.com/cycloid-community-catalog/docs-step-by-step-stack/Step4-azure/stack-sample/terraform/module-azure/variables.tf
wget -O stack-sample/terraform/module-azure/vm.tf https://raw.githubusercontent.com/cycloid-community-catalog/docs-step-by-step-stack/Step4-azure/stack-sample/terraform/module-azure/vm.tf
wget -O stack-sample/pipeline/pipeline.yml https://raw.githubusercontent.com/cycloid-community-catalog/docs-step-by-step-stack/Step4-azure/stack-sample/pipeline/pipeline.yml

sed -i "s#subnet_id.*#subnet_id           = \"$AZURE_SUBNET\"#g" stack-sample/terraform/main.tf
```

```
mkdir stack-sample/terraform/module-gcp

wget -O stack-sample/terraform/outputs.tf https://raw.githubusercontent.com/cycloid-community-catalog/docs-step-by-step-stack/Step4-gcp/stack-sample/terraform/outputs.tf
wget -O stack-sample/terraform/main.tf https://raw.githubusercontent.com/cycloid-community-catalog/docs-step-by-step-stack/Step4-gcp/stack-sample/terraform/main.tf
wget -O stack-sample/terraform/module-gcp/outputs.tf https://raw.githubusercontent.com/cycloid-community-catalog/docs-step-by-step-stack/Step4-gcp/stack-sample/terraform/module-gcp/outputs.tf
wget -O stack-sample/terraform/module-gcp/userdata.sh.tpl https://raw.githubusercontent.com/cycloid-community-catalog/docs-step-by-step-stack/Step4-gcp/stack-sample/terraform/module-gcp/userdata.sh.tpl
wget -O stack-sample/terraform/module-gcp/variables.tf https://raw.githubusercontent.com/cycloid-community-catalog/docs-step-by-step-stack/Step4-gcp/stack-sample/terraform/module-gcp/variables.tf
wget -O stack-sample/terraform/module-gcp/vm.tf https://raw.githubusercontent.com/cycloid-community-catalog/docs-step-by-step-stack/Step4-gcp/stack-sample/terraform/module-gcp/vm.tf
wget -O stack-sample/pipeline/pipeline.yml https://raw.githubusercontent.com/cycloid-community-catalog/docs-step-by-step-stack/Step4-gcp/stack-sample/pipeline/pipeline.yml
```

The previous lines create a Terraform module that contains the description of a cloud instance, and an init bash script to run at startup. To know more about Terraform module, feel free to read the [Terraform module documentation](https://www.terraform.io/language/modules)

Our Terraform now has the following files:

* A module under the `terraform/module-<provider_name>` directory

* A main Terraform file to simply call the module `terraform/main.tf`

* An [output](https://www.terraform.io/language/values/outputs) file `terraform/outputs.tf` to forward module outputs to the pipeline. We will use it later.

* Several files inside the module

  <!-- -->

  * Module output file `terraform/module-<provider_name>/outputs.tf` to specify which information the module will return.
  * Variables file `terraform/module-<provider_name>/variables.tf` to define what are the parameters we can pass to the module.
  * A `terraform/module-<provider_name>/vm.tf` file containing the definition of the cloud instance.
  * The template of the startup script `terraform/module-<provider_name>/userdata.sh.tpl` run in the instance

tip

Notice how customers usually use our defined variables with those specific tags `env`, `project`, `customer`, and `cycloid.io`, used by some of our features like [Logs](/reference/projects/concepts/logs.md) to filter components.

```
  tags {
    "cycloid.io" = "true"
    env          = var.env
    project      = var.project
    customer     = var.customer
  }
}
```

The `userdata.sh.tpl` startup script will use our two previously defined variables to know the URL and the version (commit id) we want to deploy on it.

*stack-sample/terraform/provider.tf*

```
variable "git_code_commit" {
  default = "origin/code"
}
variable "git_code_repo" {
  default = "https://github.com/cycloid-community-catalog/docs-step-by-step-stack.git"
}
```

Notes

We use a startup bash script to deploy the website source code on our instance to make this guide easier. On production, you might want to go using dedicated tools like [Ansible](/reference/ci-cd-pipelines/concepts/tools-integration/ansible.md)

Our new Terraform code now requires 2 variables to be run `git_code_commit` and `git_code_repo`. To get the commit id we will need a little bash script. As we will need it in the Terraform *plan* and *apply* job, we will introduce a standard YAML tip, allowing us to reuse YAML code as a template with [YAML Alias indicators](https://yaml.org/spec/1.2/spec.html#id2786196).

To summarize it will allow us to define a YAML code that we will put under `shared` section, and the name `&task-get-commit`. That we will be able to reuse using `*task-get-commit`.

*stack-sample/pipeline/pipeline.yml*

```
shared:
  - &task-get-commit
    task: get-commit
    config:
      platform: linux
      image_resource:
        type: registry-image
        source:
          repository: cycloid/cycloid-toolkit
          tag: latest
      run:
        path: /bin/bash
        args:
        - -c
        - |
          DIR=${PWD}
          echo "git_code_commit = \"$(cat git_code/.git/ref)\"" | tee -a extracted-vars/terraform.tfvars
          echo "git_code_repo = \"${GIT_CODE_REPO}\"" | tee -a extracted-vars/terraform.tfvars
      params:
        ENV: ((env))
        GIT_CODE_REPO: ((code_git_public_repository))
      inputs:
        - name: git_code
      outputs:
        - name: extracted-vars
          path: "extracted-vars"
```

The code above defines a pipeline [task](https://concourse-ci.org/tasks.html) used in our `terraform plan` and `terraform apply` jobs. The task expects our website source code (`git_code`) as input. Then run a bash script to generate a terraform variables file `terraform.tfvars` in the defined output `extracted-vars`.

The Terraform code is now ready to be tested and applied. To follow best practices, we will implement a "manual validation" in the pipeline to run `terraform apply` after a `terraform plan`.

Let's now define the Terraform *apply* job using our previously defined task.

*stack-sample/pipeline/pipeline.yml*

```
groups:
- name: overview
  jobs:
  - unittest
  - terraform-plan
  - terraform-apply

jobs:
  - name: terraform-plan
...
    plan:
      - do:
        - get: git_code
          trigger: true
          passed:
            - unittest
        - *task-get-commit
        - put: tfstate
          params:
            plan_only: true
            terraform_source: git_stack/stack-sample/terraform
            var_files:
              - extracted-vars/terraform.tfvars

  - name: terraform-apply
    build_logs_to_retain: 10
    plan:
      - do:
        - get: git_stack
          trigger: false
          passed:
            - terraform-plan
        - get: tfstate
          trigger: false
          passed:
            - terraform-plan
        - get: git_code
          passed:
            - terraform-plan
        - *task-get-commit
        - put: tfstate
          params:
            plan_run: true
            terraform_source: git_stack/stack-sample/terraform
            var_files:
              - extracted-vars/terraform.tfvars
```

This sample implements a manual approval by adding the `terraform-apply` without any `trigger: true` configured on the `get` resources. That means the `terraform-apply` will never be triggered automatically. The usual workflow is to trigger `terraform-plan`, let a user read the plan's output, and if it's ok, manually trigger the `terraform-apply` job by clicking on it and pressing the `+` button ![plus button](data:image/png;base64,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)

In both jobs, we added our special task defined earlier, `*task-get-commit`. As seen above, this task creates a variable file `extracted-vars/terraform.tfvars` that we specify during the call of the Terraform resource using the `var_files` option.

Add and commit those changes in **Git**:

```
git add .
git commit -m "Step 4"
git push origin stacks
```

Get back to Cycloid's dashboard, and click on the `Refresh pipeline` button ![Refresh pipeline](/assets/images/reset-pipeline-47a7ea6c1da66e9e2da26f926a41a6fd.png).

It's time to create our instance, run the `terraform-plan` job, the output should inform us that Terraform is about to create our new cloud instance:

![Terraform plan](/assets/images/terraform-plan-caeda01e55e10bb2e99fdbfcf92094f8.png)

If everything is ok for you, as described earlier, go on the `terraform-apply` job and trigger it:

![Terraform apply](/assets/images/terraform-apply-7469b2da6009593dfac32aa25c054803.png)

After the apply, a new cloud instance should be present on your cloud provider console.

***

### Key points to remember[​](#key-points-to-remember "Direct link to Key points to remember")

* You can use [Terraform module](https://www.terraform.io/language/modules/syntax) to deploy one or multiple resources and configurations
* You can reuse YAML code as a template with [YAML Alias indicators](https://yaml.org/spec/1.2/spec.html#id2786196)
* A job with no resource trigger (`trigger: false`) configured has to be triggered manually. We use to call them "manual approval"


---

# Move module call to config branch and specify Terraform sample into `.cycloid.yml`

This section introduce [Cycloid stacks concept](/reference/stacks/concepts/stack-concept.md) to improve the reusability of your stack.

* Amazon Web Services
* Microsoft Azure
* Google Cloud Platform

- Check out the `git diff` of this step [here](https://github.com/cycloid-community-catalog/docs-step-by-step-stack/commit/Step5-aws).

* Check out the `git diff` of this step [here](https://github.com/cycloid-community-catalog/docs-step-by-step-stack/commit/Step5-azure).

- Check out the `git diff` of this step [here](https://github.com/cycloid-community-catalog/docs-step-by-step-stack/commit/Step5-gcp).

![Pipeline step5](/assets/images/pipeline-step5-d430b37fc3c7b1a2c1f6618227601237.png)

We created a Terraform module during the last step and used it in a `main.tf` file inside our `stacks` branch. This step will make it more flexible and follow [Cycloid stacks concept](/reference/stacks/concepts/stack-concept.md).

Keep in mind a stack can be deployed several times for different environments or projects. The standard way to do this is to create a Terraform module in the `stacks` branch. A Terraform module should be generic and describe an application. This means if we want for an application to create two environments, `staging` and `prod`, we might want the same infrastructure but with a smaller instance size on staging. So we will describe the infrastructure in a Terraform module and call this module 2 times (one for each env) using different parameters for the instance type.

As well this concept can also be applied to other technologies like Ansible.

This is where you apply [Cycloid stacks concept](/reference/stacks/concepts/stack-concept.md). To make it simple, there is no technological limitation. It's just a way to split a `template` (here, the Terraform module) and a `parameters` of a template (here Terraform module call).

In our use-case, we will transform the call of the Terraform module `main.tf` in a sample file. Each time someone uses your stack, it will use the Terraform module from the `stacks` branch and automatically push the module's parameters in a `config` branch using your sample file. We will go more into detail about it in this step.

Follow those steps to apply all changes described in this step

* Amazon Web Services
* Microsoft Azure
* Google Cloud Platform

```
export GIT_REPO=$(git remote get-url origin)
git checkout config
git pull origin config
git checkout origin/stacks stack-sample/terraform/main.tf
mkdir -p snowy/terraform/test
git mv stack-sample/terraform/main.tf snowy/terraform/test/main.tf
git add .
git commit -m "Init an empty config branch"
git push origin config
# get back to stacks branch and apply our changes
git checkout stacks
git mv stack-sample/terraform/main.tf stack-sample/terraform/main.tf.sample
wget -O stack-sample/.cycloid.yml https://raw.githubusercontent.com/cycloid-community-catalog/docs-step-by-step-stack/Step5-aws/stack-sample/.cycloid.yml
wget -O stack-sample/pipeline/variables.sample.yml https://raw.githubusercontent.com/cycloid-community-catalog/docs-step-by-step-stack/Step5-aws/stack-sample/pipeline/variables.sample.yml
wget -O stack-sample/pipeline/pipeline.yml https://raw.githubusercontent.com/cycloid-community-catalog/docs-step-by-step-stack/Step5-aws/stack-sample/pipeline/pipeline.yml
sed -i "s#git@github.com:cycloid-community-catalog/docs-step-by-step-stack.git#$GIT_REPO#" stack-sample/pipeline/variables.sample.yml
```

```
export GIT_REPO=$(git remote get-url origin)
git checkout config
git pull origin config
git checkout origin/stacks stack-sample/terraform/main.tf
mkdir -p snowy/terraform/test
git mv stack-sample/terraform/main.tf snowy/terraform/test/main.tf
git add .
git commit -m "Init an empty config branch"
git push origin config
# get back to stacks branch and apply our changes
git checkout stacks
git mv stack-sample/terraform/main.tf stack-sample/terraform/main.tf.sample
wget -O stack-sample/.cycloid.yml https://raw.githubusercontent.com/cycloid-community-catalog/docs-step-by-step-stack/Step5-azure/stack-sample/.cycloid.yml
wget -O stack-sample/pipeline/variables.sample.yml https://raw.githubusercontent.com/cycloid-community-catalog/docs-step-by-step-stack/Step5-azure/stack-sample/pipeline/variables.sample.yml
wget -O stack-sample/pipeline/pipeline.yml https://raw.githubusercontent.com/cycloid-community-catalog/docs-step-by-step-stack/Step5-azure/stack-sample/pipeline/pipeline.yml
sed -i "s#git@github.com:cycloid-community-catalog/docs-step-by-step-stack.git#$GIT_REPO#" stack-sample/pipeline/variables.sample.yml
sed -i "s/azure_resource_group_name:.*/azure_resource_group_name: $AZURE_RESOURCE_GROUP_NAME/g" stack-sample/pipeline/variables.sample.yml
sed -i "s/azure_location:.*/azure_location: $AZURE_LOCATION/g" stack-sample/pipeline/variables.sample.yml
sed -i "s/azure_env:.*/azure_env: $AZURE_ENV/g" stack-sample/pipeline/variables.sample.yml
sed -i "s/terraform_storage_container_name:.*/terraform_storage_container_name: $TERRAFORM_STORAGE_CONTAINER_NAME/g" stack-sample/pipeline/variables.sample.yml
```

```
export GIT_REPO=$(git remote get-url origin)
git checkout config
git pull origin config
git checkout origin/stacks stack-sample/terraform/main.tf
mkdir -p snowy/terraform/test
git mv stack-sample/terraform/main.tf snowy/terraform/test/main.tf
git add .
git commit -m "Init an empty config branch"
git push origin config
# get back to stacks branch and apply our changes
git checkout stacks
git mv stack-sample/terraform/main.tf stack-sample/terraform/main.tf.sample
wget -O stack-sample/.cycloid.yml https://raw.githubusercontent.com/cycloid-community-catalog/docs-step-by-step-stack/Step5-gcp/stack-sample/.cycloid.yml
wget -O stack-sample/pipeline/variables.sample.yml https://raw.githubusercontent.com/cycloid-community-catalog/docs-step-by-step-stack/Step5-gcp/stack-sample/pipeline/variables.sample.yml
wget -O stack-sample/pipeline/pipeline.yml https://raw.githubusercontent.com/cycloid-community-catalog/docs-step-by-step-stack/Step5-gcp/stack-sample/pipeline/pipeline.yml
sed -i "s#git@github.com:cycloid-community-catalog/docs-step-by-step-stack.git#$GIT_REPO#" stack-sample/pipeline/variables.sample.yml
sed -i "s/gcp_project:.*/gcp_project: $GCP_PROJECT_NAME/" stack-sample/pipeline/variables.sample.yml
```

As described above let's define our new `main.tf.sample` as a sample in the Cycloid stack (similarly to the pipeline variables sample file), we will define the Terraform sample in `.cycloid.yml` file.

*stack-sample/.cycloid.yml*

```
config:
  default:
...
    # Configuration of terraform to setup the infrastructure
    terraform:
      instance:
        path: 'terraform/main.tf.sample'
        destination: '($ project $)/terraform/($ environment $)/main.tf'
```

TIPS

Cycloid special vars can be used in `.cycloid.yml` file, in our case `'($ project $)/terraform/($ environment $)/main.tf'` will be rendered by `'snowy/terraform/test/main.tf'`.

Those lines define the path of your stack sample in the `stacks` branch and the expected path for the sample after user configuration in the `config` branch.

After this change, the next time you create a project or a new environment with this stack, the example of Terraform file to put in the Git `config` branch will be displayed, letting the user specify is own configuration:

![wizard](/assets/images/wizard-ef28edc0399faf057f24c42914dada21.png)

Then it will be automatically pushed into his [config repository](/reference/config-and-catalog-repository/.md)

Unfortunately, this does not apply to an existing env, and this is why we created the config branch and manually put this file in the commands above.

Now to make your pipeline take into account, you need to apply the concept of merging `stacks` and `config` that you will define in the pipeline with the following changes:

* Add a `git` resource for our new `config` branch.
* Add merge stack and config sample as describe in [produce a configured stack from stack and config](/reference/ci-cd-pipelines/concepts/tools-integration/terraform.md#2---creating-terraform-plan-and-apply-jobs) section.

*stack-sample/pipeline/variables.sample.yml*

```
# Branch used to store the config of the stack
config_git_branch: config
```

We define a pipeline variable to specify the branch for our new `git` resource. And as well create a new git resource for the config branch:

*stack-sample/pipeline/pipeline.yml*

```
resources:
...
# The Terraform config (will be merged with the stack)
- name: git_config
  type: git
  source:
    uri: ((git_repository))
    branch: ((config_git_branch))
    private_key: ((git_ssh_key))
    paths:
      - ((project))/terraform/((env))/*
```

Notice the `paths` section here to limit the trigger of the pipeline only if the configuration for this specific project and env change.

Then we need to merge our stack and our config inside the pipeline. We will use the same tips as the previous step based on [YAML Alias indicators](https://yaml.org/spec/1.2/spec.html#id2786196).

*stack-sample/pipeline/pipeline.yml*

```
# YAML anchors
shared:
  - &task-merge-stack-and-config
    task: merge-stack-and-config
    config:
      platform: linux
      image_resource:
        type: registry-image
        source:
          repository: cycloid/cycloid-toolkit
          tag: latest
      run:
        path: /usr/bin/merge-stack-and-config
      inputs:
        - name: git_config
          path: "config"
        - name: git_stack
          path: "stack"
      outputs:
        - name: merged-stack
          path: "merged-stack"
    params:
      CONFIG_PATH: ((project))/terraform/((env))
      STACK_PATH: stack-sample/terraform
```

This task calls a script provided by cycloid in our [cycloid-toolkit image](https://github.com/cycloidio/docker-cycloid-toolkit) to merge our two expected inputs `stack` and `config` and put the result of the merge in a `merged-stack` output. This merge also takes `CONFIG_PATH` and `STACK_PATH` as params related to the expected path of Terraform files defined in `.cycloid.yml`

Last change, add `task-merge-stack-and-config` task and `git_config` resource in our Terraform jobs to merge our config and stack before running the Terraform resource.

*stack-sample/pipeline/pipeline.yml*

```
jobs:
...
  - name: terraform-plan
    plan:
      - do:
        - get: git_stack
          trigger: true
        - get: git_config
          trigger: true
        - get: git_code
          trigger: true
          passed:
            - unittest
        - *task-merge-stack-and-config
        - *task-get-commit
        - put: tfstate
          params:
            plan_only: true
            terraform_source: merged-stack/
            var_files:
              - extracted-vars/terraform.tfvars

  - name: terraform-apply
    plan:
      - do:
        - get: git_stack
          trigger: false
          passed:
            - terraform-plan
        - get: git_config
          trigger: false
          passed:
            - terraform-plan
        - get: tfstate
          trigger: false
          passed:
            - terraform-plan
        - get: git_code
          passed:
            - terraform-plan
        - *task-merge-stack-and-config
        - *task-get-commit
        - put: tfstate
          params:
            plan_run: true
            terraform_source: merged-stack/
            var_files:
              - extracted-vars/terraform.tfvars
```

The code above adds the `get` call of our `git_config` resource, then use the YAML anchor to add a merge task before. Then we also changed the `terraform_source` from terraform (`put: tfstate`) to use the output of our merge `merged-stack` instead of the Terraform code from the stack branch.

Add and commit those changes in **Git**:

```
git add .
git commit -m "Step 5"
git push origin stacks
```

Get back to Cycloid's dashboard, and click on the `Refresh pipeline` button ![Refresh pipeline](/assets/images/reset-pipeline-47a7ea6c1da66e9e2da26f926a41a6fd.png).

***

### Key points to remember[​](#key-points-to-remember "Direct link to Key points to remember")

* A stack can be deployed several times for different environments or projects
* A Terraform module should be generic and describe an application (same thing with Ansible for example)
* A stack is a way to split a template (for example a Terraform module) and a parameters of a template (for example a Terraform module call or `main.tf`)
* Most of the time, the parameters (for example `main.tf`) is transformed in a sample file
* Each time someone uses your stack, it will use the Terraform module from the `stacks` branch and automatically push the module's parameters in a `config` branch using your sample file


---

# Add functional tests using Terraform outputs to get instance IP address

* Amazon Web Services
* Microsoft Azure
* Google Cloud Platform

- Check out the `git diff` of this step [here](https://github.com/cycloid-community-catalog/docs-step-by-step-stack/commit/Step6-aws).

* Check out the `git diff` of this step [here](https://github.com/cycloid-community-catalog/docs-step-by-step-stack/commit/Step6-azure).

- Check out the `git diff` of this step [here](https://github.com/cycloid-community-catalog/docs-step-by-step-stack/commit/Step6-gcp).

![Pipeline step6](/assets/images/pipeline-step6-174e18392b8b814637cf653f6ca4ca1e.png)

To improve the current pipeline, let's add a dummy functional test that tries to access to the website deployed on the instance.

We will get the IP address of the instance using the output defined in the Terraform module [Terraform outputs](https://www.terraform.io/language/values/outputs). Then make sure the website responds correctly with an HTTP 200 response code

Follow those steps to apply all changes described in this step

* Amazon Web Services
* Microsoft Azure
* Google Cloud Platform

```
wget -O stack-sample/pipeline/pipeline.yml https://raw.githubusercontent.com/cycloid-community-catalog/docs-step-by-step-stack/Step6-aws/stack-sample/pipeline/pipeline.yml
```

```
wget -O stack-sample/pipeline/pipeline.yml https://raw.githubusercontent.com/cycloid-community-catalog/docs-step-by-step-stack/Step6-azure/stack-sample/pipeline/pipeline.yml
```

```
wget -O stack-sample/pipeline/pipeline.yml https://raw.githubusercontent.com/cycloid-community-catalog/docs-step-by-step-stack/Step6-gcp/stack-sample/pipeline/pipeline.yml
```

To get the IP address of the instance we forward the output of the Terraform module to the pipeline in the `output.tf` file.

*stack-sample/terraform/outputs.tf*

```
output "ip_address" {
  value       = module.instance.ip_address
  description = "IP of the server"
}
```

All Terraform outputs are available in the pipeline Terraform resource.

Create a new `functional-tests` job into our pipeline:

*stack-sample/pipeline/pipeline.yml*

```
groups:
  - name: all
    jobs:
...
    - functional-tests

jobs:
...
  - name: functional-tests
    max_in_flight: 1
    build_logs_to_retain: 10
    plan:
    - do:
      - get: tfstate
        passed: [terraform-apply]
        trigger: true
      - task: test
        config:
          platform: linux
          image_resource:
            type: registry-image
            source:
              repository: cycloid/cycloid-toolkit
              tag: latest
          run:
            path: /bin/bash
            args:
            - -c
            - |
              echo "Dummy functional tests"

              # Wait 5 min ec2 up
              for i in {1..20}
              do
                STATUS=$(curl --connect-timeout 2 -s -o /dev/null -w '%{http_code}' $(jq -r .ip_address tfstate/metadata))
                if [ $STATUS -eq 200 ]; then
                  echo "Got 200! All done!"
                  exit 0
                else
                  echo "Got $STATUS :( Not done yet... (retry ${i}/20)"
                fi
                sleep 15
              done
              echo "functional tests [Failed]"
              exit 1
          inputs:
          - name: tfstate
```

First, don't forget to add the new job into to the `groups` section. Then Terraform resource `tfstate` expose Terraform outputs in a JSON file called `metadata`. Getting this resource in our job and using it as `inputs` allows us to read `tfstate/metadata` to extract our previously declared Terraform output `ip_address`.

The job above is a bash script using the IP address from `tfstate/metadata` file to execute an HTTP request until it gets an HTTP code 200. You would expect a more complex script to fully test your application in a real production pipeline.

Add and commit those changes in **Git**:

```
git add .
git commit -m "Step 6"
git push origin stacks
```

Get back to Cycloid's dashboard, and click on the `Refresh pipeline` button ![Refresh pipeline](/assets/images/reset-pipeline-47a7ea6c1da66e9e2da26f926a41a6fd.png).

Then have a look at the `functional-tests` log to see the awesome result of our functional test:

![functional-tests](/assets/images/functional-tests-dde3148dc972a8854daa7a8110d208ff.png)

***

### Key points to remember[​](#key-points-to-remember "Direct link to Key points to remember")

* Pipeline resources allow to share information between jobs
* It's always good to read resources documentation to know what they can expose to jobs
* In our case the Terraform resource expose Terraform `outputs` to jobs


---

# Generate notifications, using Cycloid events as example

* Amazon Web Services
* Microsoft Azure
* Google Cloud Platform

- Check out the `git diff` of this step [here](https://github.com/cycloid-community-catalog/docs-step-by-step-stack/commit/Step7-aws).

* Check out the `git diff` of this step [here](https://github.com/cycloid-community-catalog/docs-step-by-step-stack/commit/Step7-azure).

- Check out the `git diff` of this step [here](https://github.com/cycloid-community-catalog/docs-step-by-step-stack/commit/Step7-gcp).

![Pipeline step7](/assets/images/pipeline-step7-1b5dfad9fc33df5a2d8a9bc14cb811d7.png)

Most of our customers ask to send notifications for pipeline status on Slack, Github, etc.

The best approach to sending notifications is to use resources. Pipelines are flexible, and resources can add many functionalities. You can integrate any notification type by using [existing resource](https://resource-types.concourse-ci.org/) or by [creating your own](https://concourse-ci.org/implementing-resource-types.html).

Let's use [Cycloid events](/reference/events/.md) as example of notification.

Before using events, we advise you to

1. [Create a Cycloid API key](/reference/api/.md) with `all actions` for testing purposes.
2. Put the API key inside a Cycloid credential to be able to use it easily inside the pipeline.

Create a dedicated [**custom credential type**](/reference/credentials/.md) called `custom_cyclobot-api-key` containing a field `key` like this:

![creds-cyclobot](/assets/images/creds-cyclobot-14ad32fc9814dcd140d6c8aa5d02a80a.png)

This should produce a Vault credential with `custom_cyclobot-api-key.key` as the path and key to access it.

Also, and you might already know the next step, if we want to keep our pipeline generic, we must define a new variable for the API key before using it in our pipeline:

Follow those steps to apply all changes described in this step

* Amazon Web Services
* Microsoft Azure
* Google Cloud Platform

```
export GIT_REPO=$(git remote get-url origin)
wget -O stack-sample/pipeline/variables.sample.yml https://raw.githubusercontent.com/cycloid-community-catalog/docs-step-by-step-stack/Step7-aws/stack-sample/pipeline/variables.sample.yml
wget -O stack-sample/pipeline/pipeline.yml https://raw.githubusercontent.com/cycloid-community-catalog/docs-step-by-step-stack/Step7-aws/stack-sample/pipeline/pipeline.yml
sed -i "s#git@github.com:cycloid-community-catalog/docs-step-by-step-stack.git#$GIT_REPO#" stack-sample/pipeline/variables.sample.yml
```

```
export GIT_REPO=$(git remote get-url origin)
wget -O stack-sample/pipeline/variables.sample.yml https://raw.githubusercontent.com/cycloid-community-catalog/docs-step-by-step-stack/Step7-azure/stack-sample/pipeline/variables.sample.yml
wget -O stack-sample/pipeline/pipeline.yml https://raw.githubusercontent.com/cycloid-community-catalog/docs-step-by-step-stack/Step7-azure/stack-sample/pipeline/pipeline.yml
sed -i "s#git@github.com:cycloid-community-catalog/docs-step-by-step-stack.git#$GIT_REPO#" stack-sample/pipeline/variables.sample.yml
sed -i "s/azure_resource_group_name:.*/azure_resource_group_name: $AZURE_RESOURCE_GROUP_NAME/g" stack-sample/pipeline/variables.sample.yml
sed -i "s/azure_location:.*/azure_location: $AZURE_LOCATION/g" stack-sample/pipeline/variables.sample.yml
sed -i "s/azure_env:.*/azure_env: $AZURE_ENV/g" stack-sample/pipeline/variables.sample.yml
sed -i "s/terraform_storage_container_name:.*/terraform_storage_container_name: $TERRAFORM_STORAGE_CONTAINER_NAME/g" stack-sample/pipeline/variables.sample.yml
```

```
export GIT_REPO=$(git remote get-url origin)
wget -O stack-sample/pipeline/variables.sample.yml https://raw.githubusercontent.com/cycloid-community-catalog/docs-step-by-step-stack/Step7-gcp/stack-sample/pipeline/variables.sample.yml
wget -O stack-sample/pipeline/pipeline.yml https://raw.githubusercontent.com/cycloid-community-catalog/docs-step-by-step-stack/Step7-gcp/stack-sample/pipeline/pipeline.yml
sed -i "s#git@github.com:cycloid-community-catalog/docs-step-by-step-stack.git#$GIT_REPO#" stack-sample/pipeline/variables.sample.yml
sed -i "s/gcp_project:.*/gcp_project: $GCP_PROJECT_NAME/" stack-sample/pipeline/variables.sample.yml
```

*stack-sample/pipeline/variables.sample.yml*

```
# Cycloid events configuration
api_key: ((custom_cyclobot-api-key.key))
api_url: https://http-api.cycloid.io
```

At this point, we are ready to configure a new `cycloid-events` resource in the pipeline and use it in our job:

*stack-sample/pipeline/pipeline.yml*

```
resource_types:
...
  - name: cycloid-events
    type: registry-image
    source:
      repository: cycloid/cycloid-events-resource

resources:
...
  - name: cycloid-events
    type: cycloid-events
    source:
      api_key: ((api_key))
      api_url: ((api_url))
      icon: fa-code-branch
      organization: ((customer))
      severity: info
      type: Custom
      tags:
        - key: project
          value: ((project))
        - key: env
          value: ((env))
        - key: customer
          value: ((customer))

jobs:
...
  - name: functional-tests
    plan:
    - do:
...
      on_failure:
        do:
        - put: cycloid-events
          params:
            severity: crit
            message: Oops
            title: The deployment of ((project)) owl have failed on ((env)) environment
      on_success:
        do:
        - put: cycloid-events
          params:
            message: Congrats !
            title: Successful deployment of ((project)) owl on ((env)) environment
```

First, define a new type of resource, `cycloid-events`, and configure it in the `resources` section. Finally, add a pipeline [step hook](https://concourse-ci.org/modifier-and-hook-steps.html) for success and failure, which call the `cycloid-events` resource.

Add and commit those changes in **Git**:

```
git add .
git commit -m "Step 7"
git push origin stacks
```

Get back to Cycloid's dashboard, and click on the `Refresh pipeline` button ![Refresh pipeline](/assets/images/reset-pipeline-47a7ea6c1da66e9e2da26f926a41a6fd.png).

After running the pipeline, a new Cycloid event should be visible on the event view:

![event](/assets/images/event-4109ac3a27f7237d4fe4182a9609360b.png)

***

### Key points to remember[​](#key-points-to-remember "Direct link to Key points to remember")

* You can integrate any notification type by using [existing resource](https://resource-types.concourse-ci.org/) or by [creating your own](https://concourse-ci.org/implementing-resource-types.html)
* You can use [Cycloid events](/reference/events/.md) as example of notification
* You can add a pipeline [step hook](https://concourse-ci.org/modifier-and-hook-steps.html) for success and failure


---

# Using StackForms to simplify the configuration

* Amazon Web Services
* Microsoft Azure
* Google Cloud Platform

- Check out the `git diff` of this step [here](https://github.com/cycloid-community-catalog/docs-step-by-step-stack/commit/Step8-aws).

* Check out the `git diff` of this step [here](https://github.com/cycloid-community-catalog/docs-step-by-step-stack/commit/Step8-azure).

- Check out the `git diff` of this step [here](https://github.com/cycloid-community-catalog/docs-step-by-step-stack/commit/Step8-gcp).

In this step, we will simplify the creation of our stack by adding [Cycloid StackForms view](/reference/stackforms/.md). This feature allows users to create HTML forms on top of sample files. Those can be from pipeline variables, Terraform, and Ansible.

Follow those steps to apply all changes described in this step

* Amazon Web Services
* Microsoft Azure
* Google Cloud Platform

```
export GIT_REPO=$(git remote get-url origin)
wget -O stack-sample/.forms.yml https://raw.githubusercontent.com/cycloid-community-catalog/docs-step-by-step-stack/Step8-aws/stack-sample/.forms.yml
sed -i "s#git@github.com:cycloid-community-catalog/docs-step-by-step-stack.git#$GIT_REPO#" stack-sample/.forms.yml
```

```
export GIT_REPO=$(git remote get-url origin)
wget -O stack-sample/.forms.yml https://raw.githubusercontent.com/cycloid-community-catalog/docs-step-by-step-stack/Step8-azure/stack-sample/.forms.yml
sed -i "s#git@github.com:cycloid-community-catalog/docs-step-by-step-stack.git#$GIT_REPO#" stack-sample/.forms.yml
```

```
export GIT_REPO=$(git remote get-url origin)
wget -O stack-sample/.forms.yml https://raw.githubusercontent.com/cycloid-community-catalog/docs-step-by-step-stack/Step8-gcp/stack-sample/.forms.yml
sed -i "s#git@github.com:cycloid-community-catalog/docs-step-by-step-stack.git#$GIT_REPO#" stack-sample/.forms.yml
```

By adding a `.forms.yml` file into your stack, at the same level as the `.cycloid.yml` file, the [Stackforms view](/reference/stackforms/.md) will be available for stacks users.

```
default:
  pipeline:
      Application-code:
      - name: "Application git public url"
        description: "The url of the public GIT repository containing the source code of the application"
        key: code_git_public_repository
        widget: simple_text
        type: string
        default: "https://github.com/cycloid-community-catalog/docs-step-by-step-stack"
      - name: "Application git repository branch"
        description: "The branch of the public GIT repository containing the source code of the application"
        key: code_git_branch
        widget: simple_text
        type: string
        default: code

  terraform:
    configuration:
      - name: "Azure instance type"
        description: "The type of instance you want to create"
        key: instance_type
        widget: slider_list
        type: string
        values:
        - Standard_DS1_v2
        - Standard_DS2_v2
        - Standard_DS3_v2
        default: Standard_DS1_v2
```

A forms file use YAML syntax and have as top level section the [use-case name of your stack](/reference/stacks/concepts/use-cases.md). If you don't, just put `default`. Look for `use-case` in [.cycloid.yml](/reference/stacks/reference/cycloid-file.md) doc to know more about it

The second level is the name of the technology. Cycloid uses this to know how to render your `*.sample` files with the variables defined in the `.forms.yml`. In our example, we use two technologies. We defined one pipeline variable and one Terraform variable.

The third level defines visual groups `Application-code` and `configuration`. The goal is to simplify the user's understanding of the variables of a stack. You would probably create a group for Cloud provider configuration, one for the source code access, and one for the actual configuration of the application. It will visually group the widget in the Cycloid dashboard, making it easier for a user to read.

The last part is widgets. A widget defines the name of a variable (`key`) to replace in your `*.sample` files and what kind of `widget` is displayed to the user. To know more about all kinds of widgets available in Cycloid, you should look at our [Cycloid forms guide](/reference/stackforms/concepts/forms-file.md).

Add and commit those changes in **Git**:

```
git add .
git commit -m "Step 8"
git push origin stacks
```

You should be able to test forms right away for any new project or environment created with this stack.

To test it, you could try to configure a new `demo` environment.

![demo env](/assets/images/demo-env-6d407931f2de62adf95d34c981c58e06.png)

After clicking next, you should see the form view that has been configured:

![forms](/assets/images/forms-ab8d93e5b65cab072ef937d11a355f68.png)

**Get back**: We will not create a different environment right now. Let's click on `snowy`, our project name on the **top menu** to get back to our `test` environment for the next training step.

![back](data:image/png;base64,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)

***

### Key points to remember[​](#key-points-to-remember "Direct link to Key points to remember")

* We can simplify the creation of our stack by adding a [Cycloid StackForms view](/reference/stackforms/.md)
* This feature allows users to create HTML forms on top of sample files
* Those can be from pipeline variables, Terraform, and Ansible
* A forms file use YAML syntax
* StackForms need a `.forms.yml` file and offer a lot of `widget`


---

# Add cleanup job to remove everything that have been created on your cloud provider by Terraform

* Amazon Web Services
* Microsoft Azure
* Google Cloud Platform

- Check out the `git diff` of this step [here](https://github.com/cycloid-community-catalog/docs-step-by-step-stack/commit/Step9-aws).

* Check out the `git diff` of this step [here](https://github.com/cycloid-community-catalog/docs-step-by-step-stack/commit/Step9-azure).

- Check out the `git diff` of this step [here](https://github.com/cycloid-community-catalog/docs-step-by-step-stack/commit/Step9-gcp).

![Pipeline step10](/assets/images/pipeline-step9-37cb7ff005d937e8b86183d8055cf901.png)

The final step is the time to clean up what we built previously.

To remove all things created by Terraform, we will create a `destroy` job which calls a [terraform destroy](https://www.terraform.io/cli/commands/destroy) command.

Follow those steps to apply all changes described in this step

* Amazon Web Services
* Microsoft Azure
* Google Cloud Platform

```
wget -O stack-sample/pipeline/pipeline.yml https://raw.githubusercontent.com/cycloid-community-catalog/docs-step-by-step-stack/Step9-aws/stack-sample/pipeline/pipeline.yml
```

```
wget -O stack-sample/pipeline/pipeline.yml https://raw.githubusercontent.com/cycloid-community-catalog/docs-step-by-step-stack/Step9-azure/stack-sample/pipeline/pipeline.yml
```

```
wget -O stack-sample/pipeline/pipeline.yml https://raw.githubusercontent.com/cycloid-community-catalog/docs-step-by-step-stack/Step9-gcp/stack-sample/pipeline/pipeline.yml
```

*stack-sample/pipeline/pipeline.yml*

```
groups:
  - name: all
    jobs:
...
  - name: destroy
    jobs:
    - terraform-destroy

jobs:
...
  - name: terraform-destroy
    max_in_flight: 1
    build_logs_to_retain: 10
    plan:
      - do:
          - get: git_stack
            trigger: false
          - get: git_config
            trigger: false
          - *task-merge-stack-and-config
          - put: tfstate
            params:
              action: destroy
              terraform_source: merged-stack/
            get_params:
              action: destroy
```

As you are familiar enough, create a new job that gets our Git, merge parts, get the tfstate file to know the current state of what Terraform has created, then call terraform resource to destroy it. The only specificity is that we created a dedicated group for this job called `destroy` in order to have it into a dedicated section of our pipeline view.

Add and commit those changes in **Git**:

```
git add .
git commit -m "Step 9"
git push origin stacks
```

Get back to Cycloid's dashboard, and click on the `Refresh pipeline` button ![Refresh pipeline](/assets/images/reset-pipeline-47a7ea6c1da66e9e2da26f926a41a6fd.png).

Call this new job and that's it, all cleaned up!

![destroy](/assets/images/terraform-destroy-9fb3ec2ddf8ee20be6035cf9315f7857.png)

You did it! Well done. Now is the time to review our [Advanced Guide](/reference/ci-cd-pipelines/examples/snippets.md).

***

### Key points to remember[​](#key-points-to-remember "Direct link to Key points to remember")

* To remove all things created by Terraform, we create a `destroy` job which calls the [terraform destroy](https://www.terraform.io/cli/commands/destroy) command


---

# Overview

![](/img/Hibou-dev-RVB.png)

Let's have a tour together around all Cycloid features. Starting from account creation, stack deployment for you to master our ecosystem in no time.


---

# Account creation (SaaS only)

## Get 1 week's access to our sandbox environment[​](#get-1-weeks-access-to-our-sandbox-environment "Direct link to Get 1 week's access to our sandbox environment")

![](/img/sandbox.png)

If you are not a Cycloid user yet, get to know Cycloid better with an exploratory sandbox session.

* Dummy data already available for you - no need to connect your own
* Try out the features that interest you the most, in your own time
* Get to know our defining principles: govern, deploy & manage

You can get a sandbox access here: <https://www.cycloid.io/sandbox-environment>

## Create an account[​](#create-an-account "Direct link to Create an account")

To use Cycloid platform, your first mission is to create a user account.

If you are using **Cycloid SaaS version**, connect on <https://console.cycloid.io/signup>. If you are using a **dedicated or on-premise setup**, you should contact your system administrator to obtain the Cycloid console URL.

Login with a provided account or create a new one by clicking on **Sign up** link :

![Login](/assets/images/login-90cd094e2c6e333cba4ada8041b4fd91.png)

To create a new organization, click on [![Create organization](data:image/png;base64,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)](https://console.cycloid.io/organizations/new) button, then proceed with setting up a subscription plan by either contacting us.

From this point our **first steps** recommendations is to understand the [**Stack concept**](/reference/stacks/concepts/stack-concept.md). Although not necessary if you build your own Cycloid stacks, this concept is therefore important to use Cycloid public stacks because it is present in all implementation of our public stacks.

The **second advised step** is to follow our step by step documentation to [**Create your own private stack**](/reference/legacy-doc/create-my-first-stack/intro.md).

It is usually easier to start by creating your own stack to understand all the mechanisms used in our public stacks.

Our public stacks are designed to be as generic as possible. The complexity of a stack is defined by its creator, the creator chooses the parameters to be exposed to the user of the stack. Consequently more generic is a stack, the more parameters the user will have to fill to use it.

![hey](/assets/images/pirate-319ae439fed6d0900a14a275f8faa840.png) ***Hi, welcome aboard !***

:::details Free trial (SaaS only)

The **free trial** is a good way to try all the features of our product for free for a limited amount of time (30 days).

To start the free trial, simply click on the Organization icon to head to your organization page. You can find it in the main navigation bar on the top left : ![Organization button](data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAMgAAAAkCAYAAADM3nVnAAAABGdBTUEAALGPC/xhBQAAACBjSFJNAAB6JgAAgIQAAPoAAACA6AAAdTAAAOpgAAA6mAAAF3CculE8AAAABmJLR0QAAAAAAAD5Q7t/AAAACXBIWXMAAA7DAAAOwwHHb6hkAAAAB3RJTUUH5QkHCh0SG9ji2wAAF+BJREFUeNrtnHl0VVWe7z/7jDe5mUkYAoQgYyCILRQqMsTq90pKRUUZCltLrLaQrvZV6wOrqEEsR5Chn+h7amkNDVjaTKIyaASxgCSIAcQAikSGMAVICElI7nDuGd4f955DAgESkBJYfNdK1s3NPvvsvX/D/k17CwDDMByu4iquohE0TRPS9z2Iq7iKSxnK9z2A84H4vgfwHeDqln154JIXEAeQhEAAtuPgOOBcEewlECI6Nyc2tytB8K80XPICIkuCcMSits6gui5MMGximBbOZSwjQoCqSMTpCsl+neQEHZ8mY9uX8aSuUAi4NJ10IcBx4FhNkPJj9dQFI0iSQCCuIBvLwbId4n0q7VrFk54SjxSb91V8/9A0TVyyAgKw/+gJDlXWIwmQJHFFMo4QYNsOtuPQNs1PVpvEK3aulxs0TROXrIl1oKKOQ5X1yJLwdpMrEY4T9UMkSXC4KgAIOrVN/L6HdcXDcRwsywJAlmWEaNosaVJALNuOOsbi7LaMaVk4tk1Dm0dR5HM+dzZIQlBdF+ZQZR2yJGKT+V7X8qIjZm2hSILDVXUk+lXSk+Kwv+eJu0zkxMYhhECSJCTp8s8OaJrmfbYsC9u2m2zXpID4dB3TNLFt+4zMLoQgzuc7/R+OQ8Q0z3vgtuNwsLLuinAzWopoxE7iUEU9KQk6UgsUjeM4F6SYmupPUZRGjOQiHA5f1kIiSRJlZWWsXbuWlJQUBg8eTGJiIpZlnbaGjQRECIFlWRR9/gW5PbuSmODHMM1GhHIcB0mSCIcN/vLWu2z/ZhcJ/ngsyyI+zscDY+6kU8dMTNNsMcEkIaipD1MfjESN82bCOUXTfheM4vbhtECLCyHO2L65/QkBwbBJbb1BWqKvWbuIEAJVVbEsq0kinw80TePgwYOsWbOG7du3Y1kWPXv25Oabb6Zbt26YptmitblU4DgOsiyzZcsWxo0bR58+fVi4cCEpKSlN8qzS8EFVVVj4fj7PzHidMSOGMfk//hVVVTBNy9MYQghs20bTVLp3zeYvby+hdFcZkiSRnJTArT+8mc6dOpzHwEFIUBswcGheoMolkKapqIqKAxjhMBHTvGAN55oWsix/J4RpaX+19QatknzRdTlLO1epbdmyhaysLDIyMjAM44LmrygK8+fP5+WXX6asrIyqqioAkpOTyczM5IEHHmDChAkoinJZCglAXFwcHTp0oE2bNijKmV3xRqvoOA59enUjOyuTP85ZyPRX/oJhRFCUU2P0UU2ZN2gAkx97mDat00lOSqR1RquzvuxcEEIQCls4zcwHSJKEz6dTWVnFlpKtbNv+FYFQCJ/Pd96EcxwHXdP4bEMxs156hUAgiCxLZ+1PVVXWFRTy6mtveFrIbe84Drqus3LVaqbP/D+Nvj/bGIJGzEw9yzTc3XzDhg3MmzePJUuWUF1djaqqZ7SpzzV3VVX5+OOPefrpp9m5cyd9+vTh8ccfZ+LEiQwaNIgjR44wa9YslixZ0khAXH8lEokQiUQ8B9iFbdsYhuHtPA3bNjVWx3EwTfOM/VmW1ai/SCSC2cC0d/s3DKPJd5w6njPB42YhBJGISW5Od2a/MJn//fvpvPrn+eDAr375MzRNa0B8G13XWVtUzPSX/ww4tEpNpq6uHkm6sO3dtGxvBzkXizu2zbIVH7GuoAgQWJZJQoKfEXfdSW6vHCKxyTfUpo7jNPrO/dtdg9gHLMsmEonERiFOa4sQnunpOA5pqalkZXVs9C7btnEcB9u2PYI1F5Zpx8zMM6+Cu3v4/X5SU1MpKSkBYNSoUWc0Gc64lrHdrbKykjfffJOKigpuvfVWXnrpJdLT0wEwDIOJEyeyePFiVq5cyW233Ybf78eyLGRZPs1fMQzDe7+u6+i6Hp2bZZ21rUufs7XxNfB/Hcfx2kYiERzHafT/hs+3FKf5IOFwmO5dOzPr2SeYOGUmr/11Pg4w6d8fRNd1LMtC13XWrd/IpKdmcbTiGE/96t/I7dmNqS+9SSAQavEgWgrbtvH5fOSv/ISVq1YzZtS99L32WkwzwvIVH/GXv85l4uO/pGPHDjF/Kewxt6ZpyLJEKBRGCIGua57ZY5pRrUTM4T0p7K4pp6EoimdmGoaBbUcF6YYbBjB06GAqK49h21Fm0zUNIQlURUVWFEQLakNbsv/169cPTdNYvHgxJSUlCCE8IYlEIs0SEldAvv76a3bs2EFiYiJjx44lPT2dQCCAoiioqsqvf/1rRo8eja7ryLLs7ZB1dXXk5+fzxRdfoOs6N910E3l5eYhYNLS4uJg5c+bQq1cvRo0axYYNGygqKiI1NZVhw4bRu3dvzwzVNI3jx4+Tn59PSUkJfr+fvLw8brzxRk9BLV++nGXLljF48GCGDBnCokWLSElJ4f7770dVVdavX8/69espKyujffv25OXlMWDAgBYpKWgiiiVJUebp0e0a/vPZJ5j45Az++F8LaJORxvgHR6EoOuuKNjLpqZlUVh5nyhMTePAndyFJMs9MfpT4+LjvzFE8EyFVVaW6uprCovXc/uNh/DBvKDW1tfh8OqNGjmDX7j18veMbTtTVsXLVKsaOGUNqagqqqrFmbQGl337Lv4wdjSzJLFv+EUWfbUCWZPKGDmLwzQNBCBy34stxcxUSGzd9wcpPVlNbW0tu7xxuG3YrSUlJyLLM8hUfsuObnYx/+GcoikJ1TQ2L332fnaWlXNf3WsJhA0m+OJEfwzDIzc0F4N133/V2kpEjR3pC0lyf5MCBAwQCARISEujYsaMnOI7jEAqFaNu2LR06RH3MSCSCqqp8+eWXPP300xQXF1NbW4skSaSmpjJy5EgmT55MWloaO3bs4LXXXiMnJ4dPP/2UL7/8kkOHDqHrOkuXLmX69OkMGDAASZIoKirihRde4IsvvuDEiRPIsszcuXN54IEHeOyxx4iPj+ezzz7j9ddfp7S0lGXLlrFw4UJGjx5NXl4eU6dOJT8/n3A4TCAQQFVV5s2bx8MPP8yECRM8PmoOmlw1WZa8nWTalMcZ/+Aohv3zYCRJZm1RMU/8YRYVx47z+0mP8NDYEViWTTgcplfPrmR1aHde9m9LIMsyh8oP49gW2dlZ1AcCnia3LJtHfzGBgTfdQKu0VPbs3cfO0m9RFAXLMtm4aRM+n058fDzzFy5iw+fF3HXHbfzP/3ELH+Wv4oNlK5AlKWpUOVFNrqkqBYWF/O2d+Vx/3bWMGXkP5eVHeOPPf6W+vh5FUTh+vJpDhw5Hd6xQiP+a8xYHDhxgzKh7aNOmNRs+L0a9SE5t1DyOkJuby7333ktGRgZbtmxhwYIFVFdXo+t6s97rOA41NTUYhoGiKCQmJiKEoLKyknvuuYdOnTrRtWtXOnXqxKhRo6ipqaGqqopp06bxySefkJ2dzdSpU5k8eTIJCQnMmzePt956C4iaWB07diQUChEMBpk0aRK/+c1v6NixI1999RXvvfceQgj279/P888/z9q1a7n22muZOXMmjz/+OJIk8cYbb7B48eKY7+kjOzub3bt3U1JSwqBBgxg8eDB79uxh79699OrVixkzZrBq1SrGjx9PVVUVb775Jps2bfLm2hyc0aOWJAnDMMjp0YU//PrfAaLC8VRMOCY+wkP33Y1pWp7NeD6h3fNliPr6eoLBEEKSvG3cfbffH4/jOPj9fnrl5FD67bcMHjSQQ+WHqTx2jOG3/5i9ZWV8U1rKT+//F3r3ykESgqSkJLZ8WUJ9IIAkRc0uWZaprqlhXdF67rh9GLcPuxUjEqFLl2uY8Z+zKfpsA/fcdSeyoqDpURPsyy9L2H/gAL/51SQyM9shSRKB+gAbN39x0dbHFZLevXsDsHTpUrZv386CBQu4++67SU9PPytTuIEFwzC8nIo7VkVR6NOnDwkJCZSXl1NaWurtHgUFBRQXF5OTk8M777zj7S79+vVj5MiRrFmzhnHjxqEoCoFAgG7duvHiiy964wwGg7z66qscOXIEwzAoKChg27Zt9OvXj/nz55OUlARATk4O48eP59NPP2X06NHIskwgEKBr164899xz5OXlYZomiqJwyy23NJpb3759Wb16NUePHuXo0aPAdyAgDRdd13XWFBbzxFMzqayq5smJj/DQfSMwLQvbcTxn9R8hHC1lmr7X5vL+0uXU1dWxd+9e0tKizvTnxZvQNJ02rTMIhUKYpknPHt25pnM2mnYyCiRJgqNHK6kPBOncqRPBUIhwOExSYhLZnTqxb99+Im7wwraRJMH+gwdp3z6TlNQU6uvr8en6P6RAXwiBaZr07t2bnTt3cvToUbZv306PHj0YOnToaZGghnCVXHJycmy3tTxhSU5O5ne/+x2apvHqq68yY8YMr01ZWRmGYWBZFtOnT0dRFCRJorKyEl3XqaqqoqqqClmWse1ocEeSJC973b59e8+htiyLHTt2UFdXh2VZTJkyxcvcl5eXoygKhw8f5vjx46iqSigUonPnzgwYMMALhMiyTDgcpqCggM2bN3Pw4EEMw/CeaSmPnlVA7JgD5ppVlVXVPDnpER667x5M08SybBRF9nyO7zqbezZi+v1+4uJ8OLFIUUONEAyGPIJ369oFVVX5dvduSr/dRWbbtiQnJTfIFUTH7RAtrU9ISECWZE66ydGIlsuAToMzKT5dp9YIRysOvCcEhhFBU9RoDZn7/UXOFzheYEFi3bp1bN68Gdu2GTJkCP379z+rcDREeno6Pp+PUCjEkSNH6N69O5ZloarqaTVLbihWCEFFRQXvvPOOF2rVNA2fz+f5Lw2fOTWy6EIIQTAYxLZtDh48yPbt2z1F5fP5TuvPVeChUAhN01BVlYMHD/L888+zevVq6uvrSUtLIyMjg0gk0mRVwLlwRs/Ntm10TfPMqspjx6PCMXYEdfX1PD/rDZ6b+RqGEfG0g6LIF8XGPhWWZZHZri2SJLN37z788fFIkhQjosT/ffWPFBSuR1EUkpIS6ZXTg5UrV1NRWUnPnj2QZEFKSnIsDGujKAq6pmEYEUpLv8WINA45JiYmoMgSgWAAn65H682AQ+XlJCUlRXec2IEnx3FonZ5OVXU1jn2yXEPX9YsmJA2Fo7CwkOXLl1NTU8OgQYMYPnw4fr+/2T5ITk4OmZmZ1NbWsmLFCmzbxu/34/P5vAgeRJlTlmWSk5NxHIcePXpQVFTE4cOH2bt3L3v27KGkpIT58+eTlZXVKFDQlBJ1x9e2bVt0Xef6669n69atlJeXU1ZWxq5du9i6dStvvfUWrVu3xowlgxua10IIPvjgAxYsWEBubi4FBQVs3bqVJUuW0Lp162ZH9BqiSQGxbSdmVn3OpCkzqTx2nCmTJjBu7N3YjkPlsWo2l3zFH+cuYtrsP2EYBrqus3rt55TuLvvOss9NwdUaKSkpDLzpRpat+JA169Zh2zYnTpxgwaIlVB6r5Lq+uViWiRASubm92fD5RsKhMF27diEQCNK1SxcURWHZig8Jh0MEAgHmzPsbKz7KRwgQQvJMgTZtMujWtQvvvb+Mg4cOIYCPPl7F0YoKbhjQH9uyo6cD5ehumpPTg1AwxIoPP8a2LMr27WPD58VomnZRZMQVjoKCApYvX04wGGTo0KEMHz4cVVWb5RtKkkQkEiE7O5sRI0Zg2zaLFi1i2rRprFu3jsLCQt577z3+/ve/Y1kWwWAQIQT9+/enXbt2bNu2jblz51JaWsqJEyfYtm0bCxYs4MCBA6dp/abG70bLBg4cSOvWrdm0aRNz5sxhz5491NbWsnnzZt5++20qKiqaTIS6fZSXl2NZFomJiRiGQXV1Nfn5+dTU1CDH6HOmcTSF00ysaFxbiwnHLI4dr2bKExMY95O7icQKGLOz2jPzmUlMfHIGr/91PpIk6NW9C//vz//N1Cf/46I77EJIGBGDvKGDiZgR3n1vKe8u+QAhJBIS/PzrQw+S2a4dEdNElmU6tm9Pbm4vrrmmMynJyQSDQZKSE/nJqHtZuHgJf3jmBRwgs107Ro+6F133xUKEwRghBLf/eBiLl3zArJdeQRICWVG4d8RddM7OjmZ7jQjBQADLsmjdujUj772bv709n4KiIrI6dozuroDj2Ajx3UazhBAUFhayYsUKgsEgQ4YM4Y477vDqs1pCB8dxuP/++9m7dy/z5s1jxowZ/OlPf0LTNKqrq6mtraV79+7cd999+Hw+cnJyePTRR3n22WeZPXs277//PhkZGezbt4/y8nKeffZZ+vbt62XPG1YHu+9zmdYwDK6//np+/vOf8+KLLzJ16lQWLlxIamoqu3btoqKigldeeYXu3bt7PocrKK6A/eAHPyA9PZ0VK1awe/du4uPj+eabb7ziy5qaGq+9bdvnjLieJiBazKya9NQsqo5X89QT/8ZPx9zZKCsdDofp1iWbmc9M4rfPzWbu/KVoioLPp+Pz6RdI7Ga2caJab/jtP2ZA//4cOXoUTVXp0KE9fr+fcDjsJfsc2yYxMYFeOT29rdiMmFxzTWd+MWE8+w8cQJYksrKy8Pl0AoEAA37Qj169ehIfH0ckEiEtLY2fjXuAffsPEAwGade2DemtWhGOJQv/+Ye3MHDgjQCYpkm/6/+JTllZHDlylFat0khJTuZ4TQ2SJDXLV2uJbiksLGTZsmUYhsGQIUO4/fbbPSe6JcLhZuZTUlJ45plnGDp0KPn5+RQUFBAOh71Q6o9+9CN69uzpMejYsWPp0qULixYtYvXq1ezZs4f+/fszdepUhg4dCkSjgXFxcfh8vkb+h6IoxMXFeaFoWZZ55JFH6N27N4sWLWLdunWUlZUxePBgxowZw8CBA71MfFxcHJqmeTSNRCIMGzYMRVGYM2cOGzdupE+fPsyePZsPP/yQZcuWsWvXLu+9Pp8PXdfPukbeiULHcdBUlTVFxTz22xepratnyqQJ/HTMndFzHw2IerJIUGPJ8lU8+cIrmKZJq7QUXpn2W67v27tRWUBz4DjRc9qlB45TcTzYrJKVhuNQ1ahWDocNTMtEimWtdV3j07+vpbDoM375v36BT9e9Mv6oVpHRtWiUKRwOYVm2Z1/LsoRhRLx3SZJA131IUtQRb2jTKrKMJMteOYObEVZVFTMSwYxFWJqTybUdh9REHz2zUjHtM1/m4GrFLVu2sHjxYq677jqGDx+OoihnParQnHWNzl/2apzcd7mRIJe+Ll+4ptypbV1H3rZtz6po6Mu4u4okSV5tl/vZrcVy6dGwP8uyPD9EVdVGQq4oihdZi1ZOROniBmZcE62p8TTEaScKHRzq6oMkJyXy6M/v48GxdxGJmI2Fg5MVvXP/+31+//zL1J6oAyEIhQ2MyPmfBXEcB5+mNLueyx2TO3nve6I2eXVNDYvnvMfXO3Zy309G4ff7iTQQ3GhY1MI0A6f1acYI0LCt40Tj9qe2BaJnYE5pf+q4mqvRBYI4XTlnVbOr8fv27UtqaioZGRmNaubOF26/LuO60R+XORvyQ0MaNGRWN6fitpFl2StkbWjWuILkft+wjOfUdzfszw1+uKZSQx5yn3V9H/fv+Ph4r/2ZxnM6LTh5Jl0IUGSFvfsPkdkmA0mWmtREQgiMSIQ1hRupqKzC54vVaGkaN9/wT6S3Sj2vbLoQgkAowld7j2Gfo8z7bHC1UDAYpHjjZjIy0sntnYNpNi/U+X3DcSAnO43EeK35Ca2YSXW5lp9fimjy0oaoaaCetnOcCleKT4Xj2BfEiEJA6f5qqmpDyJK4oASbJEn4/X5MM0IgELzkEpmnzR2wHIdkv06PrNQWPXu2KNFVnB+avLQhWtFrIIR01sWOFq+FcZzGZ9JlWbpAIgkyMxKoqQ9jO9E49PkKiW3bVFdXe2HQSxluolEAmRl+JCFadCb9qmBcHDTJNdEEzLkfluWoM6UosvdzoYRyHAe/T6VTmyRwwKZlEZ3TxyhfNsJhOw5ZbZJIite+9wsbriKKS5JzHMchIzWe7HZJUbPDurKZxXKixfWd2iTRtlX8FX+Ly+WES/riOCEEdUGDQ5X11NSFT97Le0mOtqWTw7slMileIzPDT1L8xcm0X8X54ZK/WRHwbPH6UOTk3bwR6/IWEgGqIhOnK6Qk6CTEqS32Oa7i4uOyEBAX0WxpbMuL3fZ+ucKt7o2WnrTsaqGr+Mfhkr569FScLDPnyrlq8Qq5h/tKxmUjIC6E9+sqruLi4/8DD89CV7zq6BsAAAAldEVYdGRhdGU6Y3JlYXRlADIwMjEtMDktMDdUMTA6Mjk6MTgtMDQ6MDCnBi5UAAAAJXRFWHRkYXRlOm1vZGlmeQAyMDIxLTA5LTA3VDEwOjI5OjE4LTA0OjAw1luW6AAAABJ0RVh0U29mdHdhcmUAR3JlZW5zaG90XlUIBQAAAABJRU5ErkJggg==)

From there, click on the "**Start free trial**" button, confirm your action and you're done !

![Organization button](/assets/images/start-free-trial-8a8c45c541e3615e9fc7ccbddd3a9be3.png)

You can keep track of your **free trial** status by hovering your mouse cursor on the info box located in the top right corner of the app, next to the profile and help menu. The same thing can be done by by heading up to your Organization page and checking out your subscription plan status :

![Free trial status](/assets/images/free-trial-status-ad1c4ef84f0eb132a4698ac5be804ea0.png)

Remember subscription plans are allocated *"per organization"* and not *"per account"*. This means you can create as many organizations as you need. :::


---

# Configuration

At Cycloid, we strive to use Git as much as possible to store infrastructure as code, automation, and configuration.

If you are part of a new organization, follow these steps to create a `config repository` in your organization. A config repository is the combination of a credential and the URL of a Git repository in which to store your configuration files.

## Create credentials[​](#create-credentials "Direct link to Create credentials")

Cycloid's credentials manager securly stores, accesses, and distributes secrets like API keys, AWS IAM/STS credentials, X.509 certificates, SSH credentials, and more.

**Why use it?**

There are two reasons to use it:

* You want to use a Cycloid feature that requires external access, e.g., the pricing feature on AWS requires AWS IAM access key
* You want to securely provide sensitive information to a [stack](/reference/stacks/concepts/stack-concept.md), e.g., database password or SSH key to access a private Git repository

**Create a SSH credential**

A Cycloid organization require at least one `config repository` (a Git repository) configured. To do so, we have to create access credentials to be able to clone and push into a Git repository.

Click on `Security` then `Credentials` in the left menu of the platform

![menu\_creds](data:image/png;base64,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)

Then click on the `Add credential` button and create the credential of the `ssh` type

![SSH](/assets/images/ssh-creds-2b9e52f72e323144783e97a359b0aaef.png)

## Config repositories[​](#config-repositories "Direct link to Config repositories")

Creating or updating the `config repository` from the platform is overall an easy task.

For first, navigate to the config repository list page, then click on the *Add config repository* button to access the config repository creation form:

![Add Private Config Repository button](/assets/images/add-config-repository-btn-0664f10ff829dea8b56f9d79bbd3114c.png)

From here, you'll need to add five information:

* A name for your config repository
* The Git repository url in SSH format of your `config repository` (i.e. `git@github.com:demonstration/my-config-repository.git`)
* A previously created credential
* The branch of your choice which will be used to store all the configurations
* Having a config repository as default means having it pre-selected by default during a Cycloid project creation

![Create a Config Repository](/assets/images/config-repository-create-7cef6776dbe3afe4da5f9c181f39b154.png)

warning

The specified Git repository has to be accessible by Cycloid's API and potentially by Cycloid workers if you want to use it inside a pipeline.

To update a `config repository` you can go the config repository list page and click on the one you want to edit.

## Create a Cycloid worker[​](#create-a-cycloid-worker "Direct link to Create a Cycloid worker")

As introduced in immerse section, a Cycloid pipeline require to create a worker to execute it. Before going to the next section please follow the [worker deployment](/reference/ci-cd-pipelines/concepts/workers/.md) documentation.


---

# Deploy

Today there are 2 ways to start a new project in Cycloid:

1. Selecting an existing `stack`
2. Using Infra Import (by TerraCognita) to import an existing infrastructure from your Cloud provider as a stack

## Create my first project with pre-configured resources[​](#create-my-first-project-with-pre-configured-resources "Direct link to Create my first project with pre-configured resources")

This exercise aims to create a project using the pre-configured resources provided, to show best practices and to save time.

## Naming your project[​](#naming-your-project "Direct link to Naming your project")

You should give your project name and description using a shared convention that includes useful, deducible information so team members won't get confused between different projects.

### Before you begin[​](#before-you-begin "Direct link to Before you begin")

The following sections will guide you through the deployment of the Cycloid getting started `stack`. The goal is to create a compute instance on your desired cloud provider. Depending on the chosen provider, you'll need to provide several elements.

* AWS
* Azure
* Google Cloud Platform

- An empty [**AWS S3 buckets**](https://docs.aws.amazon.com/quickstarts/latest/s3backup/step-1-create-bucket.html) with **versioning enabled**
  * `($ organization_canonical $)-terraform-remote-state`: in order to store your [Terraform remote state file](https://www.terraform.io/language/state/remote)

- **AWS access key**:

  <!-- -->

  * Require permissions to create and execute a AWS EC2 instance
  * Also require read and write permissions on the previous S3 bucket

Then create a Cycloid credential to store your cloud provider access into Cycloid

* **AWS access**: Create a second credential of `aws` type

- An empty [**Azure blob storage and an Azure blob container**](https://docs.microsoft.com/en-us/azure/storage/blobs/storage-blobs-introduction)

  * Storage: `($ organization_canonical $)tfstate` (make sure you respect the Azure storage name restrictions)
  * Container: `($ organization_canonical $)`

- **Azure** [credentials](https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs#authenticating-to-azure)
  * `client_id`, `subscription_id`, `tenant_id`, ...

- A subnet id from an [Azure virtual network/subnet](https://docs.microsoft.com/en-us/azure/virtual-network/quick-create-portal) on which we will be able to create a VM

Then create a Cycloid credentials to store your cloud provider access into Cycloid

* **Azure storage:** create a second credential of type `azure_storage`.
* **Azure credential:** create a third credential of `azure` type

- An empty [**GCP object storage bucket**](https://cloud.google.com/storage/docs/creating-buckets):
  <!-- -->
  * `($ organization_canonical $)-terraform-remote-state`: in order to store your [Terraform remote state file](https://www.terraform.io/language/state/remote).

- [**GCP service account key**](https://cloud.google.com/iam/docs/creating-managing-service-accounts):

  <!-- -->

  * Require permissions to create and execute a GCP compute instance
  * Also require read and write permissions on the previous object storage bucket

Then create a Cycloid credential to store your cloud provider access into Cycloid

* **GCP service account key:** create a second credential of `gcp` type

### Project[​](#project "Direct link to Project")

To start your journey, start by creating a new project. On the left menu click on `All Projects`

![](/img/menu_projects.png)

Then click on the button `Create new project` and enter a project name

![](/img/project_name.png)

### Select a stack[​](#select-a-stack "Direct link to Select a stack")

A list of all available `stacks` will be displayed, including Cycloid public stacks and private stacks in your organization.

![Stacks](/assets/images/stacks-3e69207a164131b0c1471df4fb9903d3.png)

Let's begin by using the **getting started** stack. Type in the search area `getting-started` and select the getting started stack.

![](/img/stack_started.png)

### Environments[​](#environments "Direct link to Environments")

An environment describe a deployment of a `stack`. Stacks are automated and reproducible via [Infrastructure as Code](/reference/stacks/concepts/iac-and-gitops.md) (IaC). Which mean, for each new environments you will deploy the same infrastructure but you can specify different configuration and variables.

Commonly, environments are named `dev`, `staging` and `prod`, but this is just a convention and can be anything.

![](/img/project_env.png)

Make sure the `Use StackForms interface` is checked and click the next button.

Select the **use-case** you would like to use and proceed to the configuration section.

This is not always the case but a `stack` can provide different use-cases. Those are usually here for a stack to offer to the end-user the choice between different deployment workflow or cloud providers for example.

Here in the getting started stack, each usecase correspond to a public **cloud provider**. Select the one you would like to test and jump to the next section.

![project\_usecase](/assets/images/project_usecase-609976b8438dfc7030bb6873caa77c4c.png)

### Configuration[​](#configuration "Direct link to Configuration")

If the `Use StackForms interface` is enabled a user-friendly form with widgets, hints and dropdowns will be used to configure your `stack`.

**Form view** by StackForms

* Amazon Web Services
* Azure
* Google Cloud Platform

![](/img/getting_started_aws1.png)

Then click on **Terraform** section

![](/img/getting_started_aws2.png)

![](/img/getting_started_azure1.png)

Then click on **Terraform** section

![](/img/getting_started_azure2.png)

![](/img/getting_started_gcp1.png)

Then click on **Terraform** section

![](/img/getting_started_gcp2.png)

:::details Optional code editor view

This view is usually reserved for advanced users who want to use specific configurations. In the code editor view all configuration and pipeline template of your stack will be editable in a text editor.

![Variables](/assets/images/variables-92cb5459b5e5834e9480483d65990f15.png) :::

On the right side section, an estimation of the cost to create the infrastructure is given via our **Cost estimation** feature.

This estimation is done by our opensource tool [TerraCost](/reference/oss/terracost.md) based on a price estimation given by reading Terraform files.

![Variables](/assets/images/project_terracost-e5020ecc9a846a3eb86f7ef4bd84d6d9.png)

After configuring the environment, click the `Next` button to review and run.

## Review & Run[​](#review--run "Direct link to Review & Run")

![](/img/project_review.png) ![](/img/project_progress.png)

A config repository is required to store the configuration of your project like pipeline variables and configuration files for the `stack`. After reviewing the infrastructure and configuration, simply press `Run` and you can start exploring the management part of the onboarding.


---

# Manage

After creating a project environment, the corresponding pipeline will be displayed. The purpose of this pipeline is to manage the entire workflow, from testing and building the source code to deploying it in production, as well as notifications, creating the target infrastructure, and any other step you can imagine.

The pipeline you have created with the getting started `stack` looks like this:

![getting\_started\_pipeline](/assets/images/getting_started_pipeline-29b023da7199a88f821a61323556b85b.png)

The `terraform-plan` job executes the terraform plan command using the previously configured parameters and the source code from the getting started `stack`. Running the plan command creates an executable plan. By default, creating the plan involves:

* Reading the current state of all existing remote objects to ensure that the Terraform state is up to date
* Comparing the current configuration to the previous state and noting any differences
* Providing a set of change actions that should make the remote objects match the configuration if applied

Once the job is done, information on how to access the created instance will be displayed in the job's log: ![project\_getting\_started\_pipeline\_success](/assets/images/project_getting_started_pipeline_success-3773a9e7aca8d2eeae5ec4b94d7dcdd6.png)

Congratulations! You have successfully deployed your first Cycloid `stack`!

![](/img/Hibou-reveillon.png)

### Clean up[​](#clean-up "Direct link to Clean up")

Before continuing your journey with Cycloid, remember that it is easy to clean up all resources created by the getting started `stack`, by using the terraform destroy job. Click on the `destroy` view to display the `terraform-destroy` job

![](/img/getting_started_pipeline_destroy.png)

As before, you can click on the job and hit ![plus-button](data:image/png;base64,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) button to trigger a destroy.


---

# Pipeline training support

# .1 Concept

* [ ] [Stack concept](/reference/stacks/concepts/stack-concept.md)

* [ ] [Pipeline template vs running pipeline](/reference/ci-cd-pipelines/.md)

* [ ] [Deploy a dummy stack](https://github.com/cycloid-community-catalog/stack-dummy/tree/master/pipeline)
  * A pipeline is composed of variables and template

* [ ] [intro to yaml](https://concourse-ci.org/config-basics.html#intro-to-yaml)

  * Warning: indentation is really important
  * It's better to use space rather than TAB

# .2 How read a pipeline (UX only)

* <!-- -->
  Pipeline view: Status color

* <!-- -->
  Jobs and resources: Resource link jobs

* <!-- -->

  Resources: example git: can git code from git (git clone) but also push datas into git (git push)

  <!-- -->

  * Resources version: when you click on it you have all the history of versions
  * Resources link jobs. This is the only way to link jobs
  * Version can be disabled or pinned, for example for rollback

* <!-- -->

  job

  <!-- -->

  * contain builds / build logs
  * Interact with Resources and execute desired actions
  * Can be paused / unpaused
  * Automatic / manual triggers
  * We can clear cache on tasks

* <!-- -->

  Pipeline

  <!-- -->

  * can be paused/unpaused
  * Edited / reset
  * Group / views

* <!-- -->
  Pipeline overview

# .3 Going deeper in jobs/resources

* <!-- -->
  Resource

```
  resources:
    - name: git_code
      type: git
      source:
        uri: https://github.com/cycloidio/cycloid.git
        branch: code
```

* [ ] <!-- -->Jobs steps are tasks interact with resources. [Job code example, step by step](https://github.com/cycloid-community-catalog/docs-step-by-step-stack/blob/stacks/stack-lambda/pipeline/pipeline.yml#L125-L160)

  * tasks: are scripts
  * resource: can be used in GET / PUT

* [ ] <!-- -->Main [pipeline sections](https://concourse-ci.org/pipelines.html)

  * Resources: configuration of resources
  * resource\_types: Additional resource to use <https://resource-types.concourse-ci.org/>
  * Jobs: jobs definition
  * groups: configure pipeline view by groups jobs in dedicated views

* [ ] <!-- -->Build your own resource (Resources are docker images) [Concourse doc](https://concourse-ci.org/implementing-resource-types.html)

  * [Cycloid events resource](https://github.com/cycloidio/cycloid-events-resource)
  * Google keyword `concourse terraform resource`

# .4 Writing jobs

Starting point:

* <!-- -->

  Write my first job task

  <!-- -->

  * Like resources, jobs run under a docker image
  * You can provide your own
  * isolated from others

```
jobs:
  - name: job-hello-world
    plan:
      - task: hello-world
        config:
          platform: linux
          image_resource:
            type: registry-image
            source:
              repository: alpine
          run:
            path: /bin/sh
            args:
              - '-ec'
              - |
                echo toto
```

* [ ] <!-- -->specific params

  * **serial**: Default false. If set to true, builds will queue up and execute one-by-one, rather than executing in parallel.
  * **serial\_groups**: Can be useful for example if there is several jobs running terraform.
  * **max\_in\_flight**: If set, specifies a maximum number of builds to run at a time. If serial or serial\_groups are set, they take precedence and force this value to be 1.
  * **build\_logs\_to\_retain**: <https://concourse-ci.org/jobs.html#schema.job.build_log_retention>

* [ ] <!-- -->Task params

```
          run:
            path: /bin/sh
            args:
              - '-ec'
              - |
                find $MSG
          params:
            MSG: "titi"
```

* <!-- -->

  task cache

  <!-- -->

  * Show before and after cache
  * Show clear cache

```
            args:
              - '-ec'
              - |
                mkdir -p datas
                date >> datas/runs
                cat datas/runs
```

```
          caches:
           - path: datas
```

* <!-- -->
  Interact with a resource
  <!-- -->
  * explain PUT and GET

```
resources:
  - name: git_code
    type: git
    source:
      uri: https://github.com/cycloid-community-catalog/docs-step-by-step-stack.git
      branch: code

jobs:
  - name: job-hello-world
    plan:
      - get: git_code
      - task: hello-world
        config:
          platform: linux
          image_resource:
            type: registry-image
            source:
              repository: alpine
          run:
            path: /bin/sh
            args:
              - '-ec'
              - |
                find .
```

* <!-- -->
  Resource trigger

```
      - get: git_code
        trigger: true
```

* <!-- -->
  task inputs (volume shared)
  <!-- -->
  * override path

```
        config:
          inputs:
          - name: git_code
          #  path: code
```

* <!-- -->

  task outputs (same as inputs)

  <!-- -->

  * using output in a different task
  * It's exactly the same to share outputs with resources

```
      - task: task1
        config:
          platform: linux
          image_resource:
            type: registry-image
            source:
              repository: alpine
          run:
            path: /bin/sh
            args:
              - '-ec'
              - |
                date > datas/output
          outputs:
            - name: datas
      - task: task2
        config:
          platform: linux
          image_resource:
            type: registry-image
            source:
              repository: alpine
          run:
            path: /bin/sh
            args:
              - '-ec'
              - |
                cat datas/output
          inputs:
            - name: datas
```

* <!-- -->

  dependencies between Jobs [Step by step example](/reference/legacy-doc/create-my-first-stack/step4.md)

  * Can be done only using resources. Cycloid tips use git commits all the way long
  * Show Cycloid resource view for a specific version (job passed)

```
resources:
  - name: git_code
    type: git
    source:
      uri: https://github.com/cycloid-community-catalog/docs-step-by-step-stack.git
      branch: code

jobs:
  - name: job1
    plan:
      - get: git_code
        trigger: true
  - name: job2
    plan:
      - get: git_code
        trigger: true
        passed: [job1]
```

* <!-- -->

  Success or failure tasks <https://concourse-ci.org/jobs.html>

  * grouping with `do`
  * Job status defined by script exit code
  * Tips adding `set -e`
  * `on_failure`, `on_success`, `on_error`, `on_abort` and `ensure`

```
jobs:
  - name: job1
    plan:
      - do:
        - task: task1
          config:
            platform: linux
            image_resource:
              type: registry-image
              source:
                repository: alpine
            run:
              path: /bin/sh
              args:
                - '-ec'
                - |
                  exit 1
        on_failure:
          do:
          - task: failure_task
            config:
              platform: linux
              image_resource:
                type: registry-image
                source:
                  repository: alpine
              run:
                path: /bin/echo
                args: ["the job failed"]
```

* <!-- -->

  Factorize some code

  <!-- -->

  * Using yaml anchor/aliases
  * Using dynamic task include [LEMP example](https://github.com/cycloid-community-catalog/stack-lemp/blob/master/pipeline/pipeline.yml#L402) this will allow to build generic pipeline. The user will define what will do the task.

```
jobs:
  - name: job1
    plan:
      - do:
        - task: mytask
          config:
            platform: linux
            image_resource:
              type: registry-image
              source:
                repository: alpine
            run:
              path: /bin/sh
              args:
                - '-ec'
                - |
                  echo foo
  - name: job2
    plan:
      - do:
        - task: mytask
          config:
            platform: linux
            image_resource:
              type: registry-image
              source:
                repository: alpine
            run:
              path: /bin/sh
              args:
                - '-ec'
                - |
                  echo foo
```

```
shared:
  - &task-mytask
    task: mytask
    config:
      platform: linux
      image_resource:
        type: registry-image
        source:
          repository: alpine
      run:
        path: /bin/sh
        args:
          - '-ec'
          - |
            echo $MESSAGE
      params:
        MESSAGE: "foo"

jobs:
  - name: job1
    plan:
      - do:
        - *task-mytask

  - name: job2
    plan:
      - do:
        - *task-mytask
```

* <!-- -->

  Going deeper with YAML anchor to pass params to a task

  <!-- -->

  * [Step by step, implement merge stack and config](/reference/legacy-doc/create-my-first-stack/step7.md)
  * [YAML anchor/aliases doc](https://yaml.org/spec/1.2/spec.html#id2786196)
  * Use them with [Cycloid toolkit](https://github.com/cycloidio/docker-cycloid-toolkit) provided scripts. Example [Magento stack](https://github.com/cycloid-community-catalog/stack-magento/blob/master/pipeline/pipeline.yml#L2)

```
shared:
  - &task-mytask
    task: mytask
    config:
      platform: linux
      image_resource:
        type: registry-image
        source:
          repository: alpine
      run:
        path: /bin/sh
        args:
          - '-ec'
          - |
            echo $MESSAGE

jobs:
  - name: job1
    plan:
      - do:
        - <<: *task-mytask
          params:
            MESSAGE: "job1"

  - name: job2
    plan:
      - do:
        - <<: *task-mytask
          params:
            MESSAGE: "job2"
```

# .5 Pipeline variables

* <!-- -->
  Regular variables. Example from the Cycloid dummy stack

* <!-- -->

  Cycloid credentials aka Vault variables (scoped to the org) [Cycloid doc](/reference/credentials/concepts.md#organize-your-custom-credential-data).

  <!-- -->

  * Different types
  * what are path and field
  * Create a `((custom_demo.message))` in the pipeline (note: this should be be used as a datastore)
  * Special vault `value` -> `((custom_demo))`

* [ ] [Cycloid vars](/reference/stacks/concepts/templating.md#special-variables) `($ organization_canonical $)`
  * Create a project and follow [magento var](https://github.com/cycloid-community-catalog/stack-magento/blob/master/pipeline/variables.sample.yml#L38) from template to running pipeline

* <!-- -->

  dynamic var name, [organize your creds](/reference/credentials/concepts.md#organize-your-custom-credential-data)

  * Vault using regular var `((custom_demo.((env))))`
  * As well you can do this with cycloid special vars into pipeline sample variables file: `((custom_demo_($ env $)))`

```
jobs:
  - name: job1
    plan:
    - task: mytask
      config:
        platform: linux
        image_resource:
          type: registry-image
          source:
            repository: alpine
        run:
          path: /bin/sh
          args:
            - '-ec'
            - |
              echo $MESSAGE
      params:
        MESSAGE: ((custom_demo.message))
        #MESSAGE: ((custom_demo))
```

```
# Reset the pipeline and illustrate by creating a new env var, the following can be used in the pipeline template
        MESSAGE: ((custom_demo.((env))))
```

* <!-- -->
  Pipeline variables can also be map/dict [variable](https://github.com/cycloid-community-catalog/stack-dockerbuild/blob/master/pipeline/variables.sample.yml#L56) used in [template](https://github.com/cycloid-community-catalog/stack-dockerbuild/blob/master/pipeline/pipeline.yml#L94)

```
code_build_args:
  FOO: 1
  BAR: 2

# This will produce
  - task: merge-stack-and-config
    config:
      <<: *merge-stack-and-config
      inputs:
      - name: git_code
        path: "config"
      - name: git_stack
        path: "stack"
    params:
      CONFIG_PATH: ((code_build_context))
      STACK_PATH: docker
      EXTRA_TAGS: ((registry_extra_tags))
      BUILD_ARGS:
          FOO: 1
          BAR: 2
      TAG_COMMIT_ID: ((registry_tag_commit_id))
```

# .6 Cycloid pipelines and Cycloid toolkit

* [ ] [Cycloid toolkit](https://github.com/cycloidio/docker-cycloid-toolkit)

  * Docker image containing scripts ready to use to simplify stacks usage
  * Opensource, based on YAML aliases/anchors
  * Example from [magento stack](https://github.com/cycloid-community-catalog/stack-magento/blob/master/pipeline/pipeline.yml#L300) pipeline [merge stack and config concept](/reference/stacks/concepts/stack-concept.md)

```
        image_resource:
          type: registry-image
          source:
            repository: cycloid/cycloid-toolkit
```

* [ ] <!-- -->pipeline samples can be found in [cycloid docs](/reference/ci-cd-pipelines/concepts/tools-integration/.md)

  * Usage of Cycloid toolkit
  * Usage of cycloid credentials
  * Integration of standard technologies like Ansible and Terraform
  * Advanced usecases

* [ ] <!-- -->Best practices and tips

  * [Reduce log outputs](/reference/ci-cd-pipelines/references/pipeline-style-guide.md)

# .7 Troubleshooting

* <!-- -->
  Keep in mind Cycloid toolkit scripts can be used in bash scripts [Cycloid doc](/reference/ci-cd-pipelines/concepts/cycloid-toolkit.md)

* <!-- -->
  Connect on a running task container using `fly intercept` [connect in a pipeline running container](/reference/ci-cd-pipelines/references/common-errors-troubleshooting.md#connect-in-a-pipeline-running-container)

* <!-- -->

  errors

  <!-- -->

  * Jobs in **errors** in **orange status**. Most of the time this status come from 3 things.

    <!-- -->

    * A dead worker.
    * A resource not configured correctly
    * Usage of a Cycloid credential which does not exist

  * We group common pipeline errors in [cycloid docs](/reference/ci-cd-pipelines/references/common-errors-troubleshooting.md#common-pipeline-errors)


---

# Terraform training support

\[\[toc]]

# Day 1

## Infrastructure as code concepts[​](#infrastructure-as-code-concepts "Direct link to Infrastructure as code concepts")

### Why use Infra As Code ?[​](#why-use-infra-as-code- "Direct link to Why use Infra As Code ?")

* [infrastructure as code](/reference/stacks/concepts/iac-and-gitops.md)

### What is terraform ?[​](#what-is-terraform- "Direct link to What is terraform ?")

* Source <https://www.terraform.io/intro>

Terraform is a tool for building, changing, and versioning infrastructure safely and efficiently. Terraform can manage existing and popular service providers as well as custom in-house solutions.

Terraform works with several public and private Cloud providers but also with other services. We will see more about Terraform providers later.

Infrastructure is described using a high-level configuration syntax ([HCL](https://github.com/hashicorp/hcl)) usually stored in `*.tf` files

**Execution Plans** Terraform has a `plan` step which shows the differences between your actual infrastructure and your configuration files, it does **nothing** on the infrastructure. Once this plan reviewed, you can `apply` it and reflect the changes on the infra.

**Resource Graph** Terraform builds a graph of all your resources, parallelizes the creation and modification of any non-dependent resources. Thanks to this, Terraform builds infrastructure as efficiently as possible and operators get insight into dependencies in their infrastructure.

**Change Automation** Complex changesets can be applied to your infrastructure with minimal human interaction. With the previously mentioned execution plan and resource graph, you know exactly what Terraform will change and in what order: avoiding hypothetical human errors.

**Aware of Drift** A status of all resources deployed during an `apply` are stored info a `tfstate` (Terraform state) file, letting Terraform know between each run, what is described into the code, what is expected to be already deployed. You are always aware about any drift (difference between the code and what is actually deployed).

## Terraform syntax bases[​](#terraform-syntax-bases "Direct link to Terraform syntax bases")

### Terraform workflow[​](#terraform-workflow "Direct link to Terraform workflow")

* `init`: Initialize local Terraform directory, downloading defined providers and modules.
* `plan`: Shows the differences between your actual infrastructure and your configuration files.
* `apply`: Deploy Terraform resources described into your code.
* `destroy`: Deploy all resources that have been created by your Terraform code.

### What is a Terraform provider ?[​](#what-is-a-terraform-provider- "Direct link to What is a Terraform provider ?")

<https://www.terraform.io/language/providers>

A Terraform provider is responsible for understanding API interactions and exposing resources. Most providers configure a specific infrastructure platform (either cloud or self-hosted). Terraform providers can also offer local utilities for tasks like generating random numbers for unique resource names.

:::details Sample

```
provider "azurerm" {
  // provider configuration
}
```

:::

### Terraform resources[​](#terraform-resources "Direct link to Terraform resources")

Resources for each Terraform providers can be found directly in [Terraform doc](https://www.terraform.io/language/providers)

In Terraform doc for a resource there is 2 important section. Example using the [network\_interface resource](https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs/resources/network_interface)

* `Argument Reference`: Argument/parameters that you can use to configure a resource
* `Attributes Reference`: Attribute that you can access/read after the creation of the resource. For example the `mac_address`, this component can be know only after creating the resource on Azure, we can't know it before.

:::details Sample

```
resource "azurerm_network_interface" "nic" {
  name                      = "myNIC"
  location                  = "westus2"
  ip_configuration {
    name                          = "myNICConfg"
    ...
  }
}
```

:::

### Accessing Resource Attributes[​](#accessing-resource-attributes "Direct link to Accessing Resource Attributes")

[Resources attributes](https://developer.hashicorp.com/terraform/language/resources#accessing-resource-attributes) are accessible in the same module with `<RESOURCE TYPE>.<NAME>.<ATTRIBUTE>`.

Attributes from a resource can be used by another resource argument. This allow you to use information from one resource in another as argument. In our example use the `id` of the created nic as argument to create our vm.

Note : it also implicitly create a dependency between the 2 resources.

:::details Sample

```
resource "azurerm_network_interface" "nic" {
  name                      = "myNIC"
  location                  = "westus2"
  ip_configuration {
    name                    = "myNICConfg"
    ...
  }
}

resource "azurerm_virtual_machine" "vm" {
  name                  = "myTFVM"
  location              = "westus2"
  network_interface_ids = [azurerm_network_interface.nic.id]
  vm_size               = "Standard_DS1_v2"
}
```

:::

### Variables types[​](#variables-types "Direct link to Variables types")

Terraform support multiple variable [types](https://www.terraform.io/language/values/variables#type-constraints) such as:

* **bool**: `true|false`
* **string**: `"foo"`
* **number**: `42`
* **list/tuple**: `["us-west-1a", "us-west-1c"]`
* **map/object**: `{name = "Mabel", age = 52}`

:::details Sample

```
variable "instance_size" {
  type    = string
  default = "Standard_DS1_v2"
}
```

:::

The `type` argument in a variable block allows you to restrict the type of value accepted, If no type constraint is set then a value of any type is accepted.

### Using Variables in a Configuration[​](#using-variables-in-a-configuration "Direct link to Using Variables in a Configuration")

Variable usage in our previous example:

:::details Sample

```
variable "instance_type" {
  type    = string
  default = "Standard_DS1_v2"
}

resource "azurerm_virtual_machine" "vm" {
  name                  = "myTFVM"
  location              = "westus2"
  vm_size               = var.instance_type
}
```

:::

tip

variables can also be concatenated with a string

:::details Sample

```
variable "instance_prefix" {
  type    = string
  default = "myname_"
}

resource "azurerm_virtual_machine" "vm" {
  name                  = "${var.instance_prefix}myTFVM"
  location              = "westus2"
  vm_size               = "Standard_DS1_v2"
}
```

:::

### Terraform outputs[​](#terraform-outputs "Direct link to Terraform outputs")

[Output](https://www.terraform.io/language/values/outputs) are like the return values of a Terraform, and have several uses:

* Outputs print certain values in the output after running `terraform apply`.
* A child module can use outputs to expose a subset of its resource attributes to a parent module (explained later in advanced section).
* When using [remote state](https://www.terraform.io/language/state/remote), outputs can be accessed via a `terraform_remote_state` data source(explained later in advanced section).

Declaring an Output Value

:::details Sample

```
resource "azurerm_virtual_machine" "vm" {
  name                  = "${var.instance_prefix}myTFVM"
  location              = "westus2"
  vm_size               = "Standard_DS1_v2"
}

output "instance_id" {
  value = azurerm_virtual_machine.vm.id
}
```

:::

### Tfstate and remote backends[​](#tfstate-and-remote-backends "Direct link to Tfstate and remote backends")

`backend` in Terraform determines how [state](https://www.terraform.io/language/state) is stored and how an operation such as apply is executed.

Benefits of backends:

* Working in a team: state shared with locks to prevent corruption
* Keeping sensitive information off disk

To store `tfstate`, Terraform supports multiple [backend](https://developer.hashicorp.com/terraform/language/backend#available-backends) such as:

* [artifactory](https://developer.hashicorp.com/terraform/language/v1.2.x/settings/backends/artifactory)
* [azurerm](https://www.terraform.io/language/settings/backends/azurerm)
* [consul](https://www.terraform.io/language/settings/backends/consul)
* [etcd](https://developer.hashicorp.com/terraform/language/v1.2.x/settings/backends/etcd)
* [gcs](https://www.terraform.io/language/settings/backends/gcs)
* [postgres](https://www.terraform.io/language/settings/backends/pg)
* [aws s3](https://www.terraform.io/language/settings/backends/s3)
* [swift](https://developer.hashicorp.com/terraform/language/v1.2.x/settings/backends/swift)

Each backend has its own configuration. It can be found on terraform docs.

:::details Sample

```

terraform {
  backend "<backend_type>" {
    key    = "path/to/my/tfstate"
    ...
  }
}
```

:::

## Terraform syntax advanced[​](#terraform-syntax-advanced "Direct link to Terraform syntax advanced")

Now the bases have been covered, this is a list of good practices / tips & tricks for a daily Terraform usage.

### Passing variables at runtime[​](#passing-variables-at-runtime "Direct link to Passing variables at runtime")

If you want to use variables, you need to define them like we seen earlier:

```
variable "my_var" {
  type    = string
  default = "my_value"
}
```

To pass the value of `my_var` at runtime, you have the following way:

* using a `terraform.tfvars`

:::details Sample

```
cat > terraform.tfvars << EOF
my_var=my_value
EOF
```

:::

* using command line

:::details Sample

```
terraform plan -var my_var="my_value"
```

:::

* using environment variables (it needs to be prefixed by `TF_VAR_`)

### Local values[​](#local-values "Direct link to Local values")

Terraform allows user to declare `local values` (or `locals`), in order to store once a value and use its reference elsewhere.\[[doc](https://www.terraform.io/language/values/locals)]

Keep in mind that this variables are not "customizable" at the runtime like the other variables. It can help you to implement more complex use-cases or dataset manipulation.

Example: a parameter which stores the result of 2 concatenate variables

:::details Sample

```
variable "project" {}
variable "env" {}
locals {
  full_name = "${var.project}-${var.env}"
}
resource "aws_instance" "example" {
  # ...
  name = local.full_name
}
```

:::

### Common functions[​](#common-functions "Direct link to Common functions")

Terraform has [built-in](https://www.terraform.io/language/functions) functions to manipulate values, example of used functions will be:

* `lower`
* `filebase64`
* `timestamp`

With this, it's possible to create more dynamics Terraform configuration.

Example:

:::details Sample

```
provider "azurerm" {
  features {}
}

resource "azurerm_virtual_machine" "vm-one" {
  name			= "myname_${timestamp()}"
  location              = "westus2"
}

resource "azurerm_virtual_machine" "vm-two" {
  name                  = lower("MyVM")
  location              = "westus2"
}
```

:::

### Terraform modules[​](#terraform-modules "Direct link to Terraform modules")

**Why**

Writing Terraform is like writing code: you can decide to write all in one "main" function or you can decide to split your code into functions. With Terraform, the equivalent is to write [modules](https://www.terraform.io/language/modules). One cool thing about modules: you can use `remote` modules using different [sources](https://www.terraform.io/language/modules/sources)

**How**

Let's write a module called `module-azure-vm`, this module will holds all the logic to create an Azure Virtual Machine. We first need to create a directory `module-azure-vm` and create the following files (it's not mandatory, but it's a good practice). To ease the process, we want to create a module, taking only one variable: the `name` of the vm and it will take care about all required stuffs.

:::details Sample

```
mkdir module-azure-vm
touch module-azure-vm/{outputs.tf,variables.tf,vm.tf}
```

:::

You seen earlier how to define `outputs` (to return the ID of the virtual machine created), `variables` and `resources`. Once the module done, we need to call it (like a function in a code).

Let's write a `azure-vm.tf` use the `source` keyword to call our freshly created module.

:::details Sample

```
module "azure-vm" {
  # call the module `module-azure-vm`
  source = "./module-azure-vm"

  # pass a variable "name" to this module
  name = "my-super-vm"
}
```

:::

As you can see, this module is called `locally` but you can call [remote](https://www.terraform.io/language/modules/sources) module. It's extremly powerful.

**Outputs**

In the same way of Terraform remote state, it's possible to use `outputs` from the module using interpolation: `module.module-azure-vm.id`. /!\ to access the output, it needs to be already defined as output *inside* the module.

### Introducing to count[​](#introducing-to-count "Direct link to Introducing to count")

Let's suppose you want to create multiple identical instances in your project, you have two solutions:

* copy/paste the Terraform resource as many as you need (not really scalable)
* use `count`

Using `count` is easy, you just need to add the `count` keyword in your ressource and TF will handle the rest ! If you want to refer to the `count`, simply use: `count.index`: it can be useful if you want to generate some unique resource name.

:::details Sample

```
resource "azurerm_virtual_machine" "vm-one" {
  count = 2

  name     = "vm-${count.index}"
  location = "westus2"
}
```

:::

### Terraform data sources[​](#terraform-data-sources "Direct link to Terraform data sources")

Using `data`, you'll be able to request data sources, like cloud provider APIs and export the result under the given local name. Example, if you want to fetch the ID of an image. This allows you to dynamically load values.

:::details Sample

```
data "azurerm_image" "search" {
  name                = "search-api"
  resource_group_name = "packerimages"
}

output "image_id" {
  value = data.azurerm_image.search.id
}
```

:::

### Data templating[​](#data-templating "Direct link to Data templating")

Sometimes, it's required to template files (configuration, user-data, etc.). With Terraform, you can perform this kind of actions with [local-only data sources](https://www.terraform.io/language/data-sources#local-only-data-sources)

:::details Sample

```
data "template_file" "my-config" {
  template = file("${path.module}/my-config.cfg")
  vars = {
    commit_id = var.commit_id
  }
}

outputs "templated" {
  config = data.template_file.rendered
}

variable "commit_id" {}
```

Let's write our config file. Using `${...}`, we let know to TF wich values we need to template:

```
cat > my-config.cfg << EOF
commit_id = ${commit_id}
EOF
```

Rendering !

```
terraform apply -var commit_id=1234
Outputs:

templated = commit_id = 1234
```

:::

### Remote tfstate data[​](#remote-tfstate-data "Direct link to Remote tfstate data")

Following the use-case, it can be a good practice to split your Terraform deployments. Let's suppose you want to segment the IAM, from the monitoring infra, from the application infra. This projects are independants but they can have some dependencies between each other. In this case, you can use remote tfstate as data source. Example: use a created user in your project `IAM` in the `monitoring` infra.

Suppose `IAM` project has `user_id` terraform output, you just need to define a `terraform_remote_state` data block and give the config following the Terraform backend used to store this tfstate (Terraform state).

:::details Sample

```
data "terraform_remote_state" "iam" {
  backend = "s3"

  config = {
    bucket = "my-bucket"
    key    = "my/path/iam.tfstate"
    region = "eu-west-1"
  }
}

resource "aws_iam_user_policy_attachment" "monitoring" {
  user       = data.terraform_remote_state.iam.outputs.user_id
  policy_arn = aws_iam_policy.monitoring.arn
}
```

:::

Then, attributes can be accesses like any other Terraform data variables: `data.terraform_remote_state.iam.outputs.<attribute>` but don't forget the `outputs` keyword.

### Terraform import[​](#terraform-import "Direct link to Terraform import")

It can happen that a resource has been deployed *without* using Terraform. In the case you can to merge it to your Terraform config, you need to `import` it.\[[doc](https://www.terraform.io/cli/import)].

For each resource you want to import, you need to take a look at the documentation and look for the `import` section. [Example](https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs/resources/virtual_machine#import) for a AzureRM virtual machine.

`import` won't generate the Terraform configuration for you, that's why you need to define an empty resource before importing it. `import` will only add a reference to this instance in the tfstate (Terraform state). Once imported, you'll be able to use this resource like any other Terraform resource.

:::details Sample

```
$ cat terraform.tf
resource "azurerm_virtual_machine" "example" {}
$ terraform import azurerm_virtual_machine.example /subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/mygroup1/providers/microsoft.compute/virtualMachines/machine1
```

:::

### Deeper in the tfstate[​](#deeper-in-the-tfstate "Direct link to Deeper in the tfstate")

In a daily usage, it's not required to know the tfstate (Terraform state) structure. It's just a JSON file actually. You can inspect it with your code editor (and even modified it but it's not recommended). Let's take a look at the structure of the file:

```
{
  "version": 4,
  "terraform_version": "0.13.3",
  "serial": 17,
  "lineage": "052943c7-75ed-5fde-6ec5-83f399c8a3f6",
  "outputs": {},
  "resources": [
    {
      "mode": "managed",
      "type": "null_resource",
      "name": "example1",
      "provider": "provider[\"registry.terraform.io/hashicorp/null\"]",
      "instances": [
        {
          "schema_version": 0,
          "attributes": {
            "id": "3541005314644017154",
            "triggers": null
          },
          "private": "bnVsbA=="
        }
      ]
    }
  ]
}
```

The most important part is the `resources` array, it holds each resource with its *current* details, this is how you keep a trace of the state of the infrastructure. Keep it mind it holds sensible data: don't push it on a Git repository but use Terraform backend instead.

### Terraform destroy[​](#terraform-destroy "Direct link to Terraform destroy")

Something to be used with caution is the `terraform destroy`. The name is self-explanatory, this command will destroy *all* the resources handled by the `tfstate`. <!-- -->⚠️<!-- --> There is no `undo`.

## Automate Terraform[​](#automate-terraform "Direct link to Automate Terraform")

### Using Terraform in a DevOps approach[​](#using-terraform-in-a-devops-approach "Direct link to Using Terraform in a DevOps approach")

We just seen the usage of Terraform. In a pure DevOps approach, it's highly recommended to run Terraform in a pipeline context. Why? It's actually easier: anyone can see everything, no bottleneck and it runs in an agnostic / neutral environment, the same for everyone.

Overall, pipeline consumes VCS resources: it means your Terraform will be tracked by a VCS (git). You will profit of all benefits offered by Git: history, tracking, revert, review by its peer, etc.

Using pipeline, you can also develop your own corporate standard fitting your businees needs, example: run a Terraform plan and wait for an external approval before running the Terraform apply.

![pipeline](https://raw.githubusercontent.com/cycloid-community-catalog/stack-terraform-runner/master/docs/pipeline.png)

### Lab 1: Hands on Terraform[​](#lab-1-hands-on-terraform "Direct link to Lab 1: Hands on Terraform")

**Cycloid prerequisites**:

* Create a private git repository `cycloid-lab-foo` and a temporary git private key `id_rsa_cycloid_lab` (deleted after X days)

* Create a config branch and add it as Cycloid default config repository

* Create a Cycloid organization `cycloid-lab-foo` with a worker available

* Add cloudprovider credentials (dedicated temporary one) + git private key

* Invite participants to the organization

* Provide to participants

  <!-- -->

  * get key `id_rsa_cycloid_lab` via pastefile
  * git repository url

#### 1. Workspace Initialization[​](#1-workspace-initialization "Direct link to 1. Workspace Initialization")

The goal is to create a virtual machine on Azure using terraform with module and variables. Terraform code will be plan/apply via cycloid [terraform-runner stack](https://github.com/cycloid-community-catalog/stack-terraform-runner)

Terraform code will be pushed on a private git repository provided by cycloid. Please be careful to not push private information.

Get the **git private key** provided by cycloid via the pastefile link.

```
mkdir cycloid-lab1
cd cycloid-lab1
curl -JO https://pastefile.owl.cycloid.io/xxxxxxxxxxxx
chmod 600 id_rsa_cycloid_lab
```

Use the provided key and git **repository url** to clone the git public repository

```
eval "$(ssh-agent -s)"
ssh-add id_rsa_cycloid_lab
git clone <REPOSITORY_URL>
cd cycloid-lab*
```

Create your own branch and files structure

```
export BRANCH_NAME="<your_name>"

git checkout --orphan $BRANCH_NAME
git rm -rf .

mkdir module-lab1
touch provider.tf main.tf outputs.tf variables.tf module-lab1/{resources.tf,variables.tf,outputs.tf}

git add .
git commit -m 'init commit'
git push origin $BRANCH_NAME
```

Wait

Validate created branch with Cycloid

#### 2. Terraform input variables[​](#2-terraform-input-variables "Direct link to 2. Terraform input variables")

Information like Cloud Provider credentials will be defined as variables and given to terraform automatically via cycloid [Terraform-runner](https://github.com/cycloid-community-catalog/stack-terraform-runner) stack.

Please [Declare](https://www.terraform.io/language/values/variables#declaring-an-input-variable) the following variables in your `variables.tf`

* `azure_location`
* `azure_env`
* `azure_client_id`
* `azure_client_secret`
* `azure_subscription_id`
* `azure_tenant_id`
* `env`
* `project`
* `customer`

Since those variables will be given to terraform, it doesn't need default value.

Add an extra variable `azure_resource_group_name` with `cycloid-lab` as default value.

:::details Correction variables.tf

```
variable "customer" {}
variable "project" {}
variable "env" {}

# Azure
variable "azure_client_id" {}
variable "azure_client_secret" {}
variable "azure_subscription_id" {}
variable "azure_tenant_id" {}
variable "azure_env" {}
variable "azure_resource_group_name" {
  default = "cycloid-lab"
}
variable "azure_location" {}
```

:::

#### 3. Provider configuration[​](#3-provider-configuration "Direct link to 3. Provider configuration")

Configure [azurerm provider](https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs) using the variables previously defined.

Latest Azurerm provider has a param [issue](https://github.com/hashicorp/terraform/issues/24200), please fix the version of your provider by adding this param `version = "=2.20.0"`

:::details Correction provider.tf

```
provider "azurerm" {
  features {}
  version         = "=2.20.0"
  environment     = var.azure_env
  client_id       = var.azure_client_id
  client_secret   = var.azure_client_secret
  subscription_id = var.azure_subscription_id
  tenant_id       = var.azure_tenant_id
}
```

:::

Wait

* `git commit/push` your code
* Invitation email from cycloid

#### 3. (bis) Validate with terraform cli[​](#3-bis-validate-with-terraform-cli "Direct link to 3. (bis) Validate with terraform cli")

Use the terraform cli to validate your code.

:::details Correction provider.tf

```
wget https://releases.hashicorp.com/terraform/0.13.4/terraform_0.13.4_linux_amd64.zip
unzip terraform_0.13.4_linux_amd64.zip

./terraform init
./terraform validate
```

:::

#### 4. Lets run terraform with Cycloid[​](#4-lets-run-terraform-with-cycloid "Direct link to 4. Lets run terraform with Cycloid")

Cycloid will be use to run your terraform code automatically. On Cycloid you will create a project using [terraform-runner stack](https://github.com/cycloid-community-catalog/stack-terraform-runner) and plug it to your github branch.

An invitation to Cycloid should have be received by email. Please create an account from the invitation link.

* Go on [cycloid console](https://console.cycloid.io), project view and create a new one.
* From the public stack, search for `terraform-runner` and `select`.
* Set an environment name (example `demo`) and click `Next`.
* Choose the Cloud Provider used for the lab
* Configurations:
* **Code git URL**: Set the provided git url (should looks like `git@github.com:cycloidio/cycloid-lab-foo.git`)
* **Code git branch**: Set your branch name
* **Terraform resource group name**: cycloid-lab
* **Terraform storage container name**: cycloid-lab
* click `Next`
* click on `Run`

Wait

* Check if your terraform-plan job succeed

#### 5. Terraform module variables[​](#5-terraform-module-variables "Direct link to 5. Terraform module variables")

Initiate your module by defining variables.

Define the following required variables:

* `project`
* `env`
* `azure_location`
* `resource_group_name`

And one variable with default value:

* `instance_size` with `Standard_B1ls` as default value.

:::details Correction module-lab1/variables.tf

```
variable "project" {}
variable "env" {}
variable "azure_location" {}
variable "resource_group_name" {}

variable "instance_size" {
  default = "Standard_B1ls"
}
```

:::

#### 6. Module call[​](#6-module-call "Direct link to 6. Module call")

To use your module code, you need to call your [module](https://www.terraform.io/language/modules) from your `main.tf` with the required attributes.

As defined in `module-lab1/variables.tf` the module requires 4 attributes:

* `project`
* `env`
* `azure_location`
* `resource_group_name`

Use your variables from `variables.tf` to define those attributes.

:::details Correction main.tf

```
module "lab1" {
  source   = "./module-lab1"
  env      = var.env
  project  = var.project

  resource_group_name = var.azure_resource_group_name
  azure_location      = var.azure_location
}
```

:::

Wait

* `git commit/push` your code
* Check if your terraform-plan job succeed

#### 7. Terraform module resources[​](#7-terraform-module-resources "Direct link to 7. Terraform module resources")

Instance and network need to be create by your terraform module. Use terraform documentation to get arguments needed.

Create a network interface (`azurerm_network_interface`). Please use `/subscriptions/508f906f-b287-4882-b038-c653fe001aa0/resourceGroups/cycloid-lab/providers/Microsoft.Network/virtualNetworks/cycloid-lab/subnets/default` for `subnet_id` param.

Create a linux instance (`azurerm_virtual_machine`) using the previous network interface.

Please define the following parameters on your `azurerm_virtual_machine`.

```
delete_os_disk_on_termination    = true
delete_data_disks_on_termination = true
```

Important

For both resources, ensure every `name` contains `project` and `env` variables.

:::details Correction module-lab1/resources.tf

```
resource "azurerm_network_interface" "main" {
  name                = "${var.project}-${var.env}-nic"
  location            = var.azure_location
  resource_group_name = var.resource_group_name

  ip_configuration {
    name                          = "${var.project}-instance-${var.env}"
    subnet_id                     = "/subscriptions/508f906f-b287-4882-b038-c653fe001aa0/resourceGroups/cycloid-lab/providers/Microsoft.Network/virtualNetworks/cycloid-lab/subnets/default"
    private_ip_address_allocation = "Dynamic"
    primary                       = true
  }
}

resource "azurerm_virtual_machine" "main" {
  name                  = "${var.project}-instance-${var.env}"
  location              = var.azure_location
  resource_group_name   = var.resource_group_name
  network_interface_ids = [azurerm_network_interface.main.id]
  vm_size               = var.instance_size

  delete_os_disk_on_termination    = true
  delete_data_disks_on_termination = true

  storage_image_reference {
    publisher = "debian"
    offer     = "debian-10"
    sku       = "10-cloudinit-gen2"
    version   = "latest"
  }

  storage_os_disk {
    name              = "${var.project}-${var.env}-disk"
    caching           = "ReadWrite"
    create_option     = "FromImage"
    managed_disk_type = "Standard_LRS"
  }
  os_profile {
    computer_name  = "demo"
    admin_username = "cycloid"
    admin_password = "vu5ba2au6eefaica0ship4Ohsai1Ueli"
  }
  os_profile_linux_config {
    disable_password_authentication = false
  }
}
```

:::

Wait

* `git commit/push` your code
* Check if your terraform-plan job succeed
* Validate with Cycloid before to run terraform-apply

#### 8. Terraform output[​](#8-terraform-output "Direct link to 8. Terraform output")

Use terraform output to get the instance id

:::details Correction module-lab1/outputs.tf

```
output "instance_id" {
  value = azurerm_virtual_machine.main.id
}
```

:::

:::details Correction outputs.tf

```
output "instance_id" {
  value       = module.lab1.instance_id
  description = "ID of your instance"
}
```

:::

Wait

* `git commit/push` your code
* Check if your terraform-plan job succeed
* Run terraform-apply and validate the instance id is displayed on the job logs

#### 9. **Validation**[​](#9-validation "Direct link to 9-validation")

Ask Cycloid to validate:

* Pipeline output
* Resources created
* Code written

Well done !

### Lab 1: advanced (Optional)[​](#lab-1-advanced-optional "Direct link to Lab 1: advanced (Optional)")

#### 10. Tags resources[​](#10-tags-resources "Direct link to 10. Tags resources")

Add at least one tag (like `environment`) on your network interface and instance.

:::details Correction module-lab1/resources.tf

```
resource "azurerm_network_interface" "main" {
...
  tags = {
    environment  = var.env
    "cycloid.io" = "true"

  }
}

resource "azurerm_virtual_machine" "main" {
...
  tags = {
    environment  = var.env
    "cycloid.io" = "true"
  }
}
```

:::

#### 11. Attach public IP[​](#11-attach-public-ip "Direct link to 11. Attach public IP")

Attach a static public ip (named with `project` and `env`) on the instance and show it with output

:::details Correction module-lab1/resources.tf

```
resource "azurerm_public_ip" "main" {
  name                = "${var.project}-${var.env}-ip"
  resource_group_name = var.resource_group_name
  location            = var.azure_location
  allocation_method   = "Static"

  tags = {
    environment  = var.env
    "cycloid.io" = "true"
  }
}

resource "azurerm_network_interface" "main" {
...
  ip_configuration {
    ...
    public_ip_address_id          = azurerm_public_ip.main.id
  }
}
```

:::

:::details Correction module-lab1/outputs.tf

```
...
output "ip_address" {
  value = azurerm_public_ip.main.ip_address
}
```

:::

:::details Correction outputs.tf

```
...
output "ip_address" {
  value       = module.lab1.ip_address
  description = "IP of the server"
}
```

:::

#### 12. Use count on instance[​](#12-use-count-on-instance "Direct link to 12. Use count on instance")

Lets say now we want 2 instances, a `loop` on resources can be done with [count](https://developer.hashicorp.com/terraform/language/resources#count-multiple-resource-instances-by-count).

Define `instance_count` variable and use count on your `azurerm_virtual_machine`.

Important

Remember to add `${count.index}` variable in your `interface name`, `instance name` and `storage_os_disk name`.

To avoid issues like `force replacement dependency` we suggest to run terraform destroy before doing a new plan/apply.

:::details Correction module-lab1/variables.tf

```
...
variable "instance_count" {
  default = 2
}
```

:::

:::details Correction module-lab1/resources.tf

```
resource "azurerm_public_ip" "main" {
  count               = var.instance_count
  name                = "${var.project}-${var.env}-ip-${count.index}"
}

resource "azurerm_network_interface" "main" {
  count               = var.instance_count
  name                = "${var.project}-${var.env}-nic-${count.index}"
  ip_configuration {
    name                          = "${var.project}-instance-${var.env}-${count.index}"
    public_ip_address_id          = azurerm_public_ip.main[count.index].id
  }
}

resource "azurerm_virtual_machine" "main" {
  count                 = var.instance_count
  name                  = "${var.project}-instance-${var.env}-${count.index}"

  network_interface_ids = [azurerm_network_interface.main[count.index].id]

  storage_os_disk {
    name              = "${var.project}-${var.env}-disk-${count.index}"
  }
}
```

:::

:::details Correction module-lab1/outputs.tf

```
output "instance_id" {
  value = azurerm_virtual_machine.main.*.id
}
output "ip_address" {
  value = azurerm_public_ip.main.*.ip_address
}
```

:::

#### 13. Use count with condition to create instances[​](#13-use-count-with-condition-to-create-instances "Direct link to 13. Use count with condition to create instances")

Let suppose we want to create network and public ip, but make instances creation optionnal with a variable.

Add `create_instances` bool variable when set to `false` the instances shouldn't be created.

:::details Correction module-lab1/variables.tf

```
variable "create_instances" {
  default = false
}
```

:::

:::details Correction module-lab1/resources.tf

```
resource "azurerm_virtual_machine" "main" {
  count                 = var.create_instances ? var.instance_count : 0
}
```

:::

#### 14. Use terraform random\_string to generate user password[​](#14-use-terraform-random_string-to-generate-user-password "Direct link to 14. Use terraform random_string to generate user password")

If it is not already the case, enable password authentication on your instances but set a random `admin_password` with [random\_string](https://registry.terraform.io/providers/hashicorp/random/latest/docs/resources/string) terraform resource.

Don't forget to set `create_instances` to `true` :::details Correction main.tf

```
module "lab1" {
  ...
  create_instances    = true
}
```

:::

:::details Correction module-lab1/resources.tf

```
resource "random_string" "password" {
  length      = 16
  min_upper   = 1
  min_lower   = 1
  min_numeric = 1
  min_special = 1
  special     = true
}

resource "azurerm_virtual_machine" "main" {
  os_profile {
    computer_name  = "demo"
    admin_username = "cycloid"
    admin_password = random_string.password.result
  }
  os_profile_linux_config {
    disable_password_authentication = false
  }
}
```

:::

# Day 2

## Terraform and CI/CD pipelines[​](#terraform-and-cicd-pipelines "Direct link to Terraform and CI/CD pipelines")

* [Concept of a stack](/reference/stacks/concepts/stack-concept.md)

![stack concept](/assets/images/stack-concept-full-9568f358499659a87105a700aa5148bf.png)

tip

Keep in mind, it's not Cycloid specific. It's a way to organize infrastructure as code. It's not required to change your code for Cycloid.

## Usage/tips from real production feedbacks[​](#usagetips-from-real-production-feedbacks "Direct link to Usage/tips from real production feedbacks")

* Sources <https://github.com/hashicorp/terraform-guides>

### Use variable as default value[​](#use-variable-as-default-value "Direct link to Use variable as default value")

We see a lot user trying to use variables in default value of others variables.

```
variable "my_name" {
  default     = "${var.project}-${var.env}"
}
```

The most common usecase is to let a user override a default name for an instance. If there is nothing specified, generate a name from `project` and `environment` variables.

**Unfortunatly** Terraform does not allow to use variable in default value for another variable.

The way to do it is to use locals:

Get the resource name from user or use a default generated from project and env variables. :::details Sample

```
variable "instance_name" {
  default     = ""
}

locals {
  instance_name = var.instance_name != "" ? var.instance_name : "${var.project}-${var.env}"
}

resource "instance" "front" {
  name        = local.instance_name
}
```

:::

### Remove unwanted chars in dynamic resource names[​](#remove-unwanted-chars-in-dynamic-resource-names "Direct link to Remove unwanted chars in dynamic resource names")

Some Terraform resources can have constraint on name, have only some specific characters allowed.

This is the case for example for `aws_alb_target_group`, which support only characters and dash.

If this name is generated by a user entry like a `project` name, you might end up with some issues.

The following code is a tips allowing you to generate a safe name for those resource which does not support all characters.

:::details Sample

```
# Allowed characters
variable "nameregex" {
  default = "/[^0-9A-Za-z-]/"
  type    = string
}

# Replace unallowed characters by ""
resource "aws_alb_target_group" "front-80" {
  name     = replace("${var.project}front80${var.env}", var.nameregex, "")
}
```

:::

**Note**: the `^` here is important, we want to match all characters not part of the list to replace them.

### Use random names when limited length[​](#use-random-names-when-limited-length "Direct link to Use random names when limited length")

As we saw previously sometime you can also have constraints on the characters length.

We encounter this issue on public modules. It's handy to keep project name as part of resource name for a better experience when devops are going on a could provider console. But sometime your user have a really long project name.

One of the solution we used to solve it:

:::details Sample

```
resource "random_string" "id" {
  length  = 20
  upper   = false
  special = false
}

resource "aws_alb_target_group" "front-80" {
  name     = length("${var.project}front80") > 32 ? "${random_string.id.result}front80" : "${var.project}front80"
}
```

:::

This code allow user with a small project name to keep it in our cloud resource name. But if the name is too long, we simply use a random generated string instead.

### Default tags from merged map[​](#default-tags-from-merged-map "Direct link to Default tags from merged map")

Tags on resources is always usefull but could be a bit redondant. Our way to handle it is to define standards and global tags in `locals`. This way it will be easier to maintain and put the same tags accross all your resources.

Also using `merge` you can also provide a convenient way for the users to also define additionals tags they want to add on all resources.

:::details Sample

```
variable "extra_tags" {
  default = {}
}

locals {
  standard_tags = {
    "cycloid.io" = "true"
    env          = var.env
    project      = var.project
    client       = var.customer
  }
  // Merging user tags with our global one
  merged_tags = merge(local.standard_tags, var.extra_tags)
}

resource "aws_security_group" "rds" {
  // Use specific resource tags and our global tags
  tags = merge(local.merged_tags, {
    Name = "${var.project}-rds-${var.env}"
    role = "rds"
  })
}
```

:::

### lookup on a map usecase[​](#lookup-on-a-map-usecase "Direct link to lookup on a map usecase")

Sometime to make a module easier to use and configure for your users `lookup` could help.

One of our latest customer usecase was the following:

Context: Our customer offer to is users to deploy instances on different regions. For each region, there is an already predefined virtual private network to use (VPC).

The first approach was to create a Terraform module to handle the creation of the instances. This module required as argument some information about the intance, the destination zone and differents network parameters like which VPC to use.

To simplify the user experience we decided to reduce the number of parameters as most of the network informations could be deduced simply by the zone used. We created maps of network configuration for each zones.

:::details Sample

```
variable "region" {
  default = "eu-west-1"
}

variable "vpc_ids" {
  default = {
    ca-central-1   = "vpc-123"
    eu-west-1      = "vpc-456"
    eu-west-2      = "vpc-789"
  }
}

resource "instance" "my_instance" {
  vpc_id      = lookup(var.vpc_ids, var.region)
}
```

:::

This way depending of the zone selected by the user, our module automatically deduce the network configuration using `lookup` function.

[See more here](https://developer.hashicorp.com/terraform/tutorials/azure-get-started/azure-variables?in=terraform%2Fazure-get-started)

### Dynamic blocks[​](#dynamic-blocks "Direct link to Dynamic blocks")

Resources using repeatable nested blocks can be [dynamically construct](https://developer.hashicorp.com/terraform/language/expressions#dynamic-blocks).

In this example, we create an AWS security group with 2 dynamically generated ingress blocks and then create an output that iterates across the ingress blocks to give us both ports.

:::details Sample

```
variable "ingress_ports" {
  type        = list(number)
  description = "list of ingress ports"
  default     = [8200, 8201]
}

resource "aws_security_group" "vault" {
  name        = "vault"

  dynamic "ingress" {
    iterator = port
    for_each = var.ingress_ports
    content {
      from_port   = port.value
      to_port     = port.value
      protocol    = "tcp"
      cidr_blocks = ["0.0.0.0/0"]
    }
  }
}
```

:::

This solution is really useful for resource which require several blocks to configure them. But keep `Overuse` of dynamic blocks can make configuration hard to read and maintain, so Terraform recommend using them only when you need to hide details in order to build a clean user interface for a re-usable module. Always write nested blocks out literally where possible.

In our case with [aws\_security\_group](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/security_group) resource its better to use the dedicated resource to create rules [aws\_security\_group\_rule](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/security_group_rule).

Advanced dynamic block using maps

:::details Sample

```
variable "settings" {
  type = list(map(string))
  default = [
     {
       namespace = "aws:ec2:vpc"
       name = "VPCId"
       value = "vpc-xxxxxxxxxxxxxxxxx"
     },
     {
       namespace = "aws:ec2:vpc"
       name = "Subnets"
       value = "subnet-xxxxxxxxxxxxxxxxx"
     },
  ]
}

resource "aws_elastic_beanstalk_environment" "tfenvtest" {
  name                = "tf-test-name"

  dynamic "setting" {
    for_each = var.settings
    content {
      namespace = setting.value["namespace"]
      name = setting.value["name"]
      value = setting.value["value"]
    }
  }
}
```

:::

[see more here](https://github.com/hashicorp/terraform-guides/tree/master/infrastructure-as-code/terraform-0.12-examples/dynamic-blocks-and-splat-expressions) and [here](https://github.com/hashicorp/terraform-guides/tree/master/infrastructure-as-code/terraform-0.12-examples/advanced-dynamic-blocks)

### Make a resources optional[​](#make-a-resources-optional "Direct link to Make a resources optional")

When creating a module sometime we want to make some resource optional. The simplest example is about network subnets. A module can create a subnet and use it. But in some context, a user might prefer to use is own existing subnet instead of creating a new one.

The sample bellow let the user a way to give the subnet group to use. If the user don't provide it, we generate one for him.

:::details Sample

```
variable "rds_subnet_group" {
  default = ""
}

resource "aws_db_subnet_group" "rds-subnet" {
  count       = var.rds_subnet_group == "" ? 1 : 0
  subnet_ids  = var.private_subnets_ids
}

resource "aws_db_instance" "application" {
  db_subnet_group_name = var.rds_subnet_group != "" ? var.rds_subnet_group : aws_db_subnet_group.rds-subnet[0].id
}
```

:::

**Note**: We also usually see it a lot for security groups and VPC. Allowing a user to provide an exisitng security group to use for an instance.

Keep in mind condition can be used to solve several usecase and can also be used with `count`. Example assign public ip only on the first instance

:::details Sample

```
resource "aws_instance" "web" {
  count                       = 3
  associate_public_ip_address = ( count.index == 1 ? true : false)
}
```

:::

### Multiple resource defined by a map, or set of strings[​](#multiple-resource-defined-by-a-map-or-set-of-strings "Direct link to Multiple resource defined by a map, or set of strings")

Interate on resource from a map or set

:::details Sample set

```
variable "users" {
  default = ["Todd", "James", "Alice", "Dottie"]
}

resource "aws_iam_user" "accounts" {
  for_each = toset( var.users )
  name     = each.key
}
```

map

```
variable "groups" {
  default = {
    group_a = "eastus"
    group_b = "westus2"
  }
}

resource "azurerm_resource_group" "rg" {
  for_each = var.groups
  name     = each.key
  location = each.value
}
```

:::

### Outputs formatting[​](#outputs-formatting "Direct link to Outputs formatting")

How create Terraform outputs from resources created by a `count` or a `for_each`.

This example show how to extract only private dns attributes of all `ubuntu` instances.

:::details Sample

```
# With old splat syntax
output "private_addresses_old" {
  value = aws_instance.ubuntu.*.private_dns
}

# With new Splat Expression
output "private_addresses_full_splat" {
  value = [ aws_instance.ubuntu[*].private_dns ]
}

# With for expression
output "private_addresses_new" {
  value = [
    for instance in aws_instance.ubuntu:
    instance.private_dns
  ]
}


# ------ Given output ------ #

private_addresses_new = [
  "ec2-54-159-217-16.compute-1.amazonaws.com",
  "ec2-35-170-33-78.compute-1.amazonaws.com",
  "ec2-18-233-162-38.compute-1.amazonaws.com",
]
```

:::

To follow our previous example, let's do the same with private IP, adding also the public IP if available.

:::details Sample

```
output "ips_with_list_interpolation" {
  value = [
    for instance in aws_instance.ubuntu:
    (instance.public_ip != "" ? list(instance.private_ip, instance.public_ip) : list(instance.private_ip))
  ]
}

# ------ Given output ------ #

ips = [
  [
    "172.16.10.218",
  ],
  [
    "172.16.10.199",
    "34.201.169.46",
  ],
  [
    "172.16.10.250",
  ],
]
```

:::

Using condition and for within template strings

:::details Sample

```
output "just_mary" {
  value = <<EOT
%{ for name in var.names ~}
%{ if name == "Mary" }${name}%{ endif ~}
%{ endfor ~}
EOT
}
```

:::

[see more here](https://github.com/hashicorp/terraform-guides/tree/master/infrastructure-as-code/terraform-0.12-examples/for-expressions#for-expressions-example)

### Terraform console[​](#terraform-console "Direct link to Terraform console")

When writing terraform code it's sometime hard to play with [expressions](https://developer.hashicorp.com/terraform/language/expressions) and functions.

Terraform provides a really nice interactive command-line console for evaluating and experimenting with [expressions](https://developer.hashicorp.com/terraform/language/expressions). This is useful for testing interpolations before using them in configurations.

:::details Sample

```
terraform console

# Get the size of a tring
> length(list("hello", "world"))
2

# inverse key and value from a map
> { for k, v in map("a", "one", "b", "two"): v => k }
{
  "one" = "a"
  "two" = "b"
}

# force uppercase on a list
[for string in ["one", "two", "three"] : upper(string)]
[
  "ONE",
  "TWO",
  "THREE",
]

# Get third ip of a subnet
> cidrhost("10.3.0.0/16", 3)
10.3.0.3
```

:::

### Terraform show/outputs[​](#terraform-showoutputs "Direct link to Terraform show/outputs")

The [terraform output](https://www.terraform.io/cli/commands/output) command is used to extract the value of an output variable from the state file. If the state is stored using a remote backend, you can omit the `state` flag.

:::details Sample

```
terraform output -state cycloid-demo.tfstate
alb_front_arn = arn:aws:elasticloadbalancing:eu-west-1:511564179444:loadbalancer/app/cycloid-front-demo/0b87325dccc3f044
alb_front_dns_name = cycloid-front-demo-548296087.eu-west-1.elb.amazonaws.com
alb_front_zone_id = Z32O12XQLNTSW2


terraform output alb_front_dns_name
cycloid-front-demo-548296087.eu-west-1.elb.amazonaws.com
```

:::

The [terraform show](https://www.terraform.io/cli/commands/show) command is used to provide human-readable output from a state or plan file. This can be used to inspect a plan to ensure that the planned operations are expected, or to inspect the current state as Terraform sees it.

Use terraform show to see the new values applied with this resources.

:::details Sample

```
terraform show
# azurerm_resource_group.rg:
resource "azurerm_resource_group" "rg" {
    id       = "/subscriptions/<subscription-id>/resourceGroups/myTFResourceGroup"
    location = "westus2"
    name     = "myTFResourceGroup"
    tags     = {
        "Environment" = "Terraform Getting Started"
        "Team"        = "DevOps"
    }
}
```

:::

### Using import in the worse case[​](#using-import-in-the-worse-case "Direct link to Using import in the worse case")

As we previously saw, `terraform import` is able to import existing infrastructure. This allows you to add manually created resources to Terraform context

In some case `terraform import` can't resolve some complex conflict or the resource is not supported by terraform import.

For example `aws_iam_access_key` can't be imported with terraform but if you want to manage it anyway you can write your terraform code matching the `aws_iam_access_key` and edit the current state by adding the resource manually.

:::details Sample

```
"aws_iam_access_key.infra": {
    "type": "aws_iam_access_key",
    "depends_on": [
        "aws_iam_user.infra"
    ],
    "primary": {
        "id": "AKIAIFOOBARRANDPBKAQ",
        "attributes": {
            "id": "AKIAIFOOBARRANDPBKAQ",
            "secret": "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",
            "status": "Active",
            "user": "infra"
        },
        "meta": {},
        "tainted": false
    },
    "deposed": [],
    "provider": "provider.aws"
},
```

:::

## Best practices[​](#best-practices "Direct link to Best practices")

### Code formatting[​](#code-formatting "Direct link to Code formatting")

[Terraform fmt](https://www.terraform.io/cli/commands/fmt) scans the current directory for configuration files and apply a subset of the Terraform language [style conventions](https://developer.hashicorp.com/terraform/language/style), along with other minor adjustments for readability.

Let's take a bad format example

```
resource "azurerm_resource_group" "rg" {
id  =              "/subscriptions/<subscription-id>/resourceGroups/myTFResourceGroup"
 location = "westus2"
    name     = "myTFResourceGroup"

tags     = { "Environment" = "Terraform Getting Started",  "Team"        = "DevOps"  }
}
```

by running `terraform fmt` your file will be updated with the following format

:::details Sample

```
resource "azurerm_resource_group" "rg" {
  id       = "/subscriptions/<subscription-id>/resourceGroups/myTFResourceGroup"
  location = "westus2"
  name     = "myTFResourceGroup"

  tags = { "Environment" = "Terraform Getting Started", "Team" = "DevOps" }
}
```

::: It allows you to push common formatting patterns for everyone writing Terraform configs. It is also a good thing to [validate](https://www.terraform.io/cli/commands/validate) your code and expressions with `terraform validate`. It will help before running you terraform code and warn you about potential deprecation.

:::details Sample

```
terraform validate

Warning: Interpolation-only expressions are deprecated

  on ecr-prod.tf line 11, in output "ecr_repository_arn":
  11:   value = "${aws_ecr_repository.ecr.arn}"

Terraform 0.11 and earlier required all non-constant expressions to be
provided via interpolation syntax, but this pattern is now deprecated. To
silence this warning, remove the "${ sequence from the start and the }"
sequence from the end of this expression, leaving just the inner expression.

Template interpolation syntax is still used to construct strings from
expressions when the template includes multiple interpolation sequences or a
mixture of literal strings and interpolations. This deprecation applies only
to templates that consist entirely of a single interpolation sequence.

(and 8 more similar warnings elsewhere)

Success! The configuration is valid, but there were some validation warnings as shown above.
```

:::

### Directory architecture & naming[​](#directory-architecture--naming "Direct link to Directory architecture & naming")

It's quite important to have a common directory architecture for your business, it eases project onboarding and allows automation on project generation. At Cycloid (and in the TF word), we recommend this tree:

```
example
├── main.tf
├── outputs.tf
├── variables.tf
├── provider.tf
├── example-module
│   ├── something.tf
│   ├── outputs.tf
│   └── variables.tf
```

You can easily guess that in the `variables.tf`, you'll find the variables. As well as outputs and cloud providers. Still in the same vein of standards, it's a good habit to give good and descriptive name to your variables. Just like any programming language: you need concise and human readable name.

**When you give a name** to an output, a resource or a variable always think about two things:

* Does my teammates will understand what's behind this name ?
* Will I remember the meaning of this name in 6 months ?

A tip would be to avoid "long" names because you can increase the typo probability.

**We would also recommend to use Terraform modules**. It will enforce you to write re-usable code and make easier the creation of several environments like dev, staging and production from the same source code. Keep also in mind you are not limited to one module. You can even split for example the network part into a module. And create a dedicated module for resources like instances which will use output of the network one.

**The name of your `tf` files is important too**. Choose a good name for your tf `something.tf` files. To simplify contribution and onboarding of new users on your code, take something clear and logic. Most of the time we would recommend to split files related to the main resources of the Cloud provider. Like `ec2.tf`,`rds.tf`, `iam.tf`, ...

why?

* It's usually easier for someone new on a project to know the Cloud provider resources name rather than internal application namming.
* It give you a better vision on what is actually used on the Cloud provider.
* Cloud provider resources name are static. Their name will "never" change versus internal component name of a project.
* Cloud provider resources are usually well defined and really specific. Project components usually evolve, we create links between components and move resource from one to another quite often.
* It's easier to iterate on resources of the same type and maintain Terraform code over the time.

### Take care about your tfstate[​](#take-care-about-your-tfstate "Direct link to Take care about your tfstate")

We have already seen a couple of things around the tfstate (Terraform state): remote backends, tfstate components, etc. We can now provide a few tips around this *special* file.

First of all, we highly recommend to **enable versionning and encrypting** of the remote backends (if supported). Enabling the versionning will save you from any accidental deletion of the tfstate and to be more confident on each Terraform actions.

It's possible to inspect the tfstate using `terraform state` subcommands. The advantage of using this command rather than inspecting directly the tfstate: you don't need to have locally it, Terraform will handle the remote backend.

```
$ terraform state --help
Subcommands:
    list                List resources in the state
    mv                  Move an item in the state
    pull                Pull current state and output to stdout
    push                Update remote state from a local state file
    replace-provider    Replace provider in the state
    rm                  Remove instances from the state
    show                Show a resource in the state
```

Using `show`, you can easily display a resource in the tfstate, since this file is the result of a `terraform apply`, the `data` will be present too ! Remember, in the `terraform plan` you can't see the data since they need to be computed by Terraform.

:::details Example with `random_shuffle` resource

```
$ cat compute.tf
data "google_compute_zones" "available" {}

resource "random_shuffle" "mail-server_zone_name" {
  input        = data.google_compute_zones.available.names
  result_count = 1
}
$ terraform state show random_shuffle.mail-server_zone_name
# random_shuffle.mail-server_zone_name:
resource "random_shuffle" "mail-server_zone_name" {
    id           = "-"
    input        = [
        "europe-west2-a",
        "europe-west2-b",
        "europe-west2-c",
    ]
    result       = [
        "europe-west2-b",
    ]
    result_count = 1
}
```

:::

Finally, when you run a `terraform apply`, Terraform will print the outputs value. It can be annoying, in a CI context, if some sensitive values are printed in the pipeline. To circumvent this, Terraform allows to add the `sensitive = true` attribute in the output definition: the output remains usable through the whole project but it won't be printed at the `apply` command.

:::details Example

```
$ cat output.tf
output "ip_address" {
  value       = module.lab1.ip_address
  description = "IP of the server"
  sensitive   = true
}
$ terraform apply
...
Outputs:

ip_address = <sensitive>
```

:::

The last thing, for several small reason it is usually better to split your infrastructure into several `tfstate` files.

It will be better for security reason and reduce the impact of a mistake like a Terraform destroy.

Most of our customers create one tfstate file per environment (`dev`, `staging` and `production`) but for really large infrastructure it could also make sense to split by sub components of an application or Cloud providers items (Like having a dedicated tfstate file for Aws route53).

**User story** One of our customer used Terraform to create his production infrastructure (Aws EC2 + RDS) and also had lot of domain name on route53 (1k+). Terraform apply was taking more than 15min only to go through all the Aws route53 domains making the deployment really long. To add more flexibility and speed up the process we finally created a dedicated Terraform module for route53 with a dedicated tfstate file.

### Think of what have to be dynamic[​](#think-of-what-have-to-be-dynamic "Direct link to Think of what have to be dynamic")

Something difficult about stack creation is the level of freedom we (as a stack designer) want to give to the stack user. A common error is to let too much freedom which results in a large variable set to understand and to fill.

Even if the variables are well documented it can be really complicated to configure a stack and the user will think that it's easier to start from scratch rather than using this stack. You don't want to fill 50 variables to create a simple Azure object storage. The best approach is to make a stack easy to use with only few parameters.

You need to think about how your user would like to config his stack: playing on fine parameters like disk type or just playing on gross parameters like number of instance without carrying of what's behind. Using Cycloid [Stackforms](https://docs.cycloid.io/guide/project.html#forms-view), you'll be able to simply expose this parameters for the user at the project creation time.

### Cloud approach tags/labels[​](#cloud-approach-tagslabels "Direct link to Cloud approach tags/labels")

Most of the time, following your cloud provider, it's possible for the user to define `tags` or `labels` (depending on your cloud provider). Using tags you can:

* easily identify a group of resources following an environment or a project
* use Ansible using dynamic inventory based on `tags` ([Azure](https://docs.microsoft.com/en-us/azure/developer/ansible/dynamic-inventory-configure?tabs=ansible#tag-a-vm) documentation)
* have meaningful billing view/report

It's a good practice to start to tag your Terraform resources and to define a smart way of tagging following your business needs. Don't hesitate to use Terraform variables and local variables to define your tags !

For example, here at Cycloid, most of the resources use the following tags:

* `client`
* `project`
* `env`: defines the environment of the resource: prod ? staging ? etc.
* `role`: if the resource belongs to a "front", a "back", a "cache" pool depending of your infra

To ease the process, we define a set of recurrent tags inside a module

```
standard_tags = {
  env          = var.env
  project      = var.project
  client       = var.customer
}
```

and we define a variable an `extra_tags` variable in the module call to add more flexibility on the tags choice.

Finally, we are merging all of this tags in a local variable to have access to it in the whole module.

```
locals {
  standard_tags = {
    "cycloid.io" = "true"
    env          = var.env
    project      = var.project
    client       = var.customer
  }
  merged_tags = merge(local.standard_tags, var.extra_tags)
}
```

### Descriptions are not useless[​](#descriptions-are-not-useless "Direct link to Descriptions are not useless")

Terraform allows the developer to define `description` for variables and outputs. It helps the Terraform final user to clearly identify the usage and the nature of a value. Like variable names, description must concisely explain the purpose of the output (or what kind of value is expected for a variable).

:::details example

```
output "instance_ip_addr" {
  value       = aws_instance.server.private_ip
  description = "The private IP address of the main server instance."
}
```

:::

## Have a look together on a production stack[​](#have-a-look-together-on-a-production-stack "Direct link to Have a look together on a production stack")

Quick look on a real production usecase. Cycloid website use our own public LEMP stack

* [Cycloid website pipeline](https://console.cycloid.io/organizations/cycloid/projects/cycloidio-website/pipelines/cycloidio-website-prod)
* [Cycloid website stack](https://github.com/cycloid-community-catalog/stack-lemp)

## Test your IAC[​](#test-your-iac "Direct link to Test your IAC")

It will help to maintain it and to identify any breaking changes. You can use the following tools to test your Terraform / Ansible:

* <https://github.com/gruntwork-io/terratest>
* <https://ansible.readthedocs.io/projects/molecule/>

## Going further with Terraform ecosystem[​](#going-further-with-terraform-ecosystem "Direct link to Going further with Terraform ecosystem")

Based on all this training, your understood how Terraform is a milestone in DevOps / Infrastructure As Code (IAC) world. There is plenty of [OSS](https://project-awesome.org/shuaibiyy/awesome-terraform) built around Terraform. At Cycloid, we decided to release two OSS based on Terraform.

* Generate TF from manually deployed resources using [Terracognita](https://github.com/cycloidio/terracognita): it supports Azure, GCP and AWS cloud providers and it's based on `terraform import` feature
* Generate TF graphs using [InfraMap](https://github.com/cycloidio/inframap): it's a refined `terraform graph` and helps you to generate Infrastructure graphs based on your tfstate or your Terraform config.

For a demo of this two tools, you can watch this meetup [video](https://youtu.be/3BqULzfWYXo?t=646) where we demonstrated Terracognita and Inframap with a simple use-case.

Finally, you can think about Terraform integration with other tools, like Ansible or a CMDB ? Using Terraform outputs, you can easily expose outputs from the `terraform apply`, why not used them to feed Ansible inventory or CMDB? Example with Ansible inventory: <https://github.com/adammck/terraform-inventory>

## Creating a Terraform stack from scratch Lab 2[​](#creating-a-terraform-stack-from-scratch-lab-2 "Direct link to Creating a Terraform stack from scratch Lab 2")

* [Cycloid step by step](/reference/legacy-doc/create-my-first-stack/intro.md)

The goal is to show Terraform implementation in a CI.

We will use Cycloid CI/CD pipelines

* [**Introduction**](/reference/legacy-doc/create-my-first-stack/intro.md) (Together)
* [**Step1**](/reference/legacy-doc/create-my-first-stack/step1.md) (Together)
* [**Step2**](/reference/legacy-doc/create-my-first-stack/step2-part1.md) (Together)

Let's go

Connect on your own Cycloid organization that has been assigned for the lab. And follow those steps on your own:

Important

Please use the following exports during the lab:

```
export AZURE_RESOURCE_GROUP_NAME=cycloid-lab
export AZURE_LOCATION="West Europe"
export AZURE_ENV=public
export TERRAFORM_STORAGE_CONTAINER_NAME=cycloid-lab
export AZURE_SUBNET="/subscriptions/508f906f-b287-4882-b038-c653fe001aa0/resourceGroups/cycloid-lab/providers/Microsoft.Network/virtualNetworks/cycloid-lab/subnets/default"
```

* [**Step3**](/reference/legacy-doc/create-my-first-stack/step3.md)
* [**Step4**](/reference/legacy-doc/create-my-first-stack/step4.md)
* [**Step5**](/reference/legacy-doc/create-my-first-stack/step5.md): Have a deeper look on the Terraform code used
* [**Step6**](/reference/legacy-doc/create-my-first-stack/step6.md)

Get back together

* [**Step7**](/reference/legacy-doc/create-my-first-stack/step7.md) (Together)
* [**Step8**](/reference/legacy-doc/create-my-first-stack/step8.md) (Together)
* [**Step9**](/reference/legacy-doc/create-my-first-stack/step9.md) (Together)

Run the following commands to implement the 3 previous steps. Then you can **call Terraform Destroy** job to cleanup your environment.

:::details Sample

```
wget -O stack-sample/pipeline/variables.sample.yml https://raw.githubusercontent.com/cycloid-community-catalog/docs-step-by-step-stack/Step9-azure/stack-sample/pipeline/variables.sample.yml
wget -O stack-sample/pipeline/pipeline.yml https://raw.githubusercontent.com/cycloid-community-catalog/docs-step-by-step-stack/Step9-azure/stack-sample/pipeline/pipeline.yml
wget -O stack-sample/.forms.yml https://raw.githubusercontent.com/cycloid-community-catalog/docs-step-by-step-stack/Step9-azure/stack-sample/.forms.yml

sed -i "s#git@github.com:cycloid-community-catalog/docs-step-by-step-stack.git#$GIT_REPO#" stack-sample/.forms.yml
sed -i "s#git@github.com:cycloid-community-catalog/docs-step-by-step-stack.git#$GIT_REPO#" stack-sample/pipeline/variables.sample.yml
sed -i "s/azure_resource_group_name:.*/azure_resource_group_name: $AZURE_RESOURCE_GROUP_NAME/g" stack-sample/pipeline/variables.sample.yml
sed -i "s/azure_location:.*/azure_location: $AZURE_LOCATION/g" stack-sample/pipeline/variables.sample.yml
sed -i "s/azure_env:.*/azure_env: $AZURE_ENV/g" stack-sample/pipeline/variables.sample.yml
sed -i "s/terraform_storage_container_name:.*/terraform_storage_container_name: $TERRAFORM_STORAGE_CONTAINER_NAME/g" stack-sample/pipeline/variables.sample.yml

git add .
git commit -n -m "steps 7,8,9"
git push origin stacks
```

:::

### Extra steps (Optional)[​](#extra-steps-optional "Direct link to Extra steps (Optional)")

**1) How use Terraform output in Ansible ?** The answer is [share-variables-between-terraform-and-ansible](/reference/ci-cd-pipelines/concepts/tools-integration/terraform.md#sharing-variables-between-terraform-and-ansible). This way Ansible is aware of all infrastructure and configuration component for a server. You could easily report all those informations to a ticket tool or an inventory software.

**2) Define resource name prefix in a variable**: Use what we saw in use-variable-as-default-value to define a default prefix `${var.customer}-${var.project}-` that a user can also override for all resources names.

**3) Make azure vm optional**: Define a new `switch` widget in your stackforms and a new `use_vm` Terraform parameter to the module to make `azurerm_virtual_machine` optional using a `count`.

## Find the answer (Optional)[​](#find-the-answer-optional "Direct link to Find the answer (Optional)")

We're now going to ask you some questions about what we have seen in this two days of Terraform training. Don't worry, you can't loose anything !

**1. In the stack `cycloid-community-catalog/stack-lemp`, what's the purpose of [this line](https://github.com/cycloid-community-catalog/stack-lemp/blob/043482c5484b9661d8eac9caa94fcbd656df86d4/terraform/module-lemp/ami.tf#L28) ?**

:::details Answer To make optionel the `aws_ami.front` resource if the user user specified an `front_ami_id` :::

**2. How would you *quickly* evaluate the base64 of a file using Terraform ?**

:::details Answer

* <https://www.terraform.io/language/functions/filebase64>

```
filebase64(path)
```

:::

**3. In the stack `cycloid-community-catalog/stack-aks`, what would be the actual tags applied to the module [resources here](https://github.com/cycloid-community-catalog/stack-aks/blob/4e2e750a85331390e4d0f6c05fda1ef5bb25d522/terraform/module-network/network.tf#L23-L25).**

:::details Answer

* [variables.tf](https://github.com/cycloid-community-catalog/stack-aks/blob/4e2e750a85331390e4d0f6c05fda1ef5bb25d522/terraform/module-network/variables.tf#L32-L35)

```
    "cycloid.io" = "true"
    env          = var.env
    project      = var.project
    client       = var.customer
```

And the tags defined by the user in `extra_tags` as well :::

**4. What's wrong with this Terraform ?**

```
$ terraform plan

Error: Unsupported attribute

  on compute.tf line 69, in resource "google_compute_firewall" "block-ping-mail-server":
  69:   network = data.google_compute_network.default.hello

This object has no argument, nested block, or exported attribute named
"hello".
```

:::details Answer

* [google\_compute\_firewall](https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/compute_firewall#attributes-reference)

The `google_compute_firewall` resource does not expose an attributes reference named `hello` :::

**5. What happens if I change infrastructure I'm managing with Terraform outside of Terraform?**

:::details Answer The change you made outside of Terraform will be overwritten the next time you apply the configuration unless you add the ignore\_changes parameter to the resource in the configuration file. :::


---

# Notifications

Notifications provide timely updates on Cycloid activity, allowing users to stay informed about changes or events.

***

## Watchrules Overview[​](#watchrules-overview "Direct link to Watchrules Overview")

Watchrules define which Cycloid activity generates notifications. They enable users to customize the scope of monitored activity, from a specific project to an entire organization, ensuring relevant notifications are received.

Two types of watchrules are available:

* **Project Activity** Track changes within a specific project. This includes, but is not limited to, deployments, resource modifications, or configuration updates.

  Note

  Only one project activity watchrule is permitted per project.

* **Event Tracking** Monitors broader, organization-wide events. Examples include pipeline events, user activity but also custom events such as monitoring alerts, across the Cycloid environment.

***

## Configuring Notifications[​](#configuring-notifications "Direct link to Configuring Notifications")

Users can configure notifications through two primary methods: direct project watching or custom watchrule creation.

### Watching a Specific Project[​](#watching-a-specific-project "Direct link to Watching a Specific Project")

To receive notifications for a project, click the **"Watch project"** button within the project interface.

![](/img/notifications_watchrule_project.png)

tip

**Automatic Watching for New Projects:** Upon project creation, Cycloid automatically establishes a "Project Activity" watchrule for the new project by default. This initiates immediate notification delivery for the project's activity. This setting can be managed in **Profile > Notifications**.

![](/img/notifications_project_create_settings.png)

To cease notifications for a project, click the **"Unwatch project"** button.

### Creating and Managing Watchrules[​](#creating-and-managing-watchrules "Direct link to Creating and Managing Watchrules")

For granular control over notification preferences, watchrules can be created and managed centrally in **Profile > Watchrules**.

![](/img/notifications_watchrules_types.png)

***

## Accessing Notifications[​](#accessing-notifications "Direct link to Accessing Notifications")

Notifications display activity generated by configured watchrules.

info

**Important Note:** Notifications are generated for actions performed by *other* users. Actions initiated by the user themselves do not generate notifications.

Notifications can be accessed from the following locations:

* **Notifications Page**: This page provides a consolidated view of all activity generated by your watchrules.

  ![](/img/notifications_page.png)

  tip

  **Email Summaries:** Users can opt to receive daily or weekly email summaries of notification activity. This option is configurable in **Profile > Notifications**.

* **Within a Specific Watchrule's Details**: When viewing an individual watchrule (e.g., `Profile > Watchrules > [Watchrule Name]`), the activity specific to that particular watchrule is displayed.

  ![](/img/notifications_watchrule_details.png)

***

## Managing Notification Preferences[​](#managing-notification-preferences "Direct link to Managing Notification Preferences")

All notification-related settings are located within the user's **Profile**:

* **Profile > Notifications**: Manages general notification settings, including automatic watching for new projects and email summary preferences.
* **Profile > Watchrules**: Provides an interface to create, modify, and delete Project Activity and Event Tracking watchrules.


---

# Organizations

## Introduction[​](#introduction "Direct link to Introduction")

An organization is the highest entity level below the user in cycloid.

Everything that you will create will be done within an organization: credentials, teams, projects, etc. A user can exist without one, but s/he will not be able to perform any actions if s/he is not part of at least one organization.

You can create and be part of multiple organizations, however they cannot communicate together, which means that if you had created some teams or credentials in one, you will not be able to access them in another one.

warning

The deletion of an organization can be done, only after all the projects have been deleted. The reasons behind this, is that the infrastructures handled by the pipelines' projects cannot be destroyed upon organization's deletion.

Which is why customers have to destroy each of their infrastructure managed by projects, and then projects to avoid having unreachable infrastructure that still generate costs on your cloud provider.


---

# Authentication

## Overview[​](#overview "Direct link to Overview")

This documentation provides an overview of how authentication work within our product and how it can be configured through the organization.

## Key Concepts[​](#key-concepts "Direct link to Key Concepts")

### Users[​](#users "Direct link to Users")

Users within the product are considered a first-class citizen entity. They exist outside of organizations but can join them (by invitation) or create them if permitted. However, an organization may enforce specific authentication requirements for connecting to the organization.

### Multi Factor Authentication[​](#multi-factor-authentication "Direct link to Multi Factor Authentication")

Currently, Cycloid supports multi-factor authentication through:

* SSO (external)
* Password + Email (builtin)

The Password + Email (Magic Link) authentication allows a user who logs in with a username/password to receive an email containing a login link. This ensures that the organization can verify the user has access to their email, thereby enhancing account security.

This feature is activated at the **user profile level** in the **Password and authentication**, where the user configures MFA via email.

From the organization's perspective, the administrator has visibility into members who have not yet activated MFA and can require all members of the organization to activate MFA to be able to log in to the organization.

![](/img/organizations/auth_mfa.png)

## Dedicated authentication[​](#dedicated-authentication "Direct link to Dedicated authentication")

Single sign-on (SSO) for your domain within Cycloid allows your Users to easily and securely log in to their accounts.

### What are Identity providers[​](#what-are-identity-providers "Direct link to What are Identity providers")

Identity providers (or SSO) are a way to authenticate and log in to an application with just one set of credentials, rather than having to set up multiple usernames and passwords across different platforms.

Cycloid is currently only compatible with the OAuth 2.0 protocol. See the section below for the list of supported providers.

### Setting up your Identity Provider[​](#setting-up-your-identity-provider "Direct link to Setting up your Identity Provider")

Organizations are able to configure their own SSO providers, the organizations members have some different options available (One of the options have to be activated.):

* Email + Password
* Email + Password and OAuth providers
* OAuth providers

By default the only option available is Email + Password, is mandatory to have at least one authentication method enabled.

When you have more than one option enabled, you can disable the Email + Password option and only leave the OAuth provider enabled.

warning

It is important to know that if you leave only the OAuth provider enabled with an incorrect SSO configuration, you will be locked out and will not be able to sign in/sign up in the affected organization.

Organizations have their own custom page for login, this url is generated automatically.

![](/img/organizations/sso_login_url.png)

Parent organizations are able to allow child organizations to have their own auth providers configuration.

![](/img/organizations/sso_own_providers.png)

When parent organizations allow child's to configure their own authentication providers, child organizations have two options:

* Inherits the configuration from the parent
* Setup their own configuration

You can make this enabling/disabling the `Configure authentication providers for this organization` option.

![](/img/organizations/sso_child_own_config.png)

### EntradID/AzureAD[​](#entradidazuread "Direct link to EntradID/AzureAD")

Configuring AzureAD, we can find it at `Organizations Settings` level in the `Authentication > Authentication providers`.

Required fields to configure are the following:

| Attribute             | Type   | Required |
| --------------------- | ------ | -------- |
| **azuread-tenant-id** | string | yes      |
| **azuread-client-id** | string | yes      |

1. Go to the Authentication section in the organization settings and click on the `Microsoft Entra ID` toggle.

![](/img/organizations/sso_toggle_azure.png)

2. A panel will appear with the following fields:

   <!-- -->

   * `Azuread Tenant ID`
   * `Azuread Client ID`

![](/img/organizations/sso_azure_panel.png)

3. Set the values for the fields.
4. Click on the `Save` button to save the changes and activate the authentication provider.

![](/img/organizations/sso_activate_azure.png)

5. Finally you can go to your custom login page and see the new option to login with Azure.

#### EntradID configuration[​](#entradid-configuration "Direct link to EntradID configuration")

On Azure Devops portal, enter the Entra ID configuration, then the App Registrations section

![](/img/organizations/sso_azure_portal.png)

On the header menu, create a new registration

![](/img/organizations/sso_azure_new_registration.png)

The application should be configured as follow

![](/img/organizations/sso_azure_config.png)

It's important to select SPA type for the redirect URL. If you have multiple environments, you can add later more redirect URI.

Azure Active Directory B2C

If using Azure Active Directory B2C, [sign-up and sign-in user flow](https://docs.microsoft.com/en-us/azure/active-directory-b2c/tutorial-create-user-flows?pivots=b2c-user-flow#create-a-sign-up-and-sign-in-user-flow) need to be created.

Here is the list of claims and attributes that need to be exposed for Cycloid.

| **Azure AD fields**        | **Cycloid fields** |
| -------------------------- | ------------------ |
| User's Object ID           | ID                 |
| Display Name or Given Name | GivenName          |
| Surname                    | FamilyName         |
| Display Name               | Canonical          |
| Email Addresses            | Email              |

Navigate to the API Permissions and ensure that the app has permissions for signing in and reading user profiles. If these permissions are missing, click `+` to add them (as shown in the screenshot below).

![API Permissions](/assets/images/api_permissions-b7987df95cae3cdb8776f2d85310d6ab.png)

### GitHub[​](#github "Direct link to GitHub")

To configure GitHub as an authentication provider, navigate to the **Organization Settings** and under **Authentication > Authentication Providers**.

The following fields are required:

| Attribute              | Type   | Required |
| ---------------------- | ------ | -------- |
| `github-client-id`     | string | Yes      |
| `github-client-secret` | string | Yes      |
| `github-host-address`  | string | No       |

info

When registering the application on GitHub, the callback URL must follow the format:<br />`<organization_url>/oauth2-callback`

Configuration Steps:

1. In the **Authentication** section of the organization settings, enable the **GitHub** provider by toggling the corresponding switch.

![](/img/organizations/sso_toggle_github.png)

2. A configuration panel will appear with the following fields:

   <!-- -->

   * GitHub Client ID
   * GitHub Client Secret

![](/img/organizations/sso_github_panel.png)

3. Enter the required values.

4. Click **Save** to apply the configuration and activate GitHub as an authentication provider.

![](/img/organizations/sso_activate_github.png)

5. The **Login with GitHub** option will now be available on your custom login page.


---

# Child organizations

Organizations can have child organizations. This can be useful to manage project and permissions between siloed Business units in your organization.

Each organization can have a different theme and configuration.

You can create a child organization by clicking on the Org menu on the top right corner and `New Organization`.

![](/img/organizations/interface-child-org-1.png)

You can then fill the organization name and choose the parent org.

![child org menu](/assets/images/interface-child-org-2-fb50849a21b8d34b3ea524ed406feee6.png)


---

# Interface

You current organization is displayed on the top right corner of the interface:

![Org interface description](/assets/images/interface-1-7d9f733215dc824db088b1d0692f5bb1.png)

If you click on your current org, you will be able to:

1. Switch quickly across all the orgs that you are member to
2. Go to the all organization panels
3. Create a new org
4. Change current organization settings

![](/img/organizations/interface-2.png)

In the `all organization panels` you will be able to list and find all organizations you have access to.

![Org interface description](/assets/images/interface-3-e8b219d267fc6768301b9469fef584c0.png)

## Organization settings[​](#organization-settings "Direct link to Organization settings")

Inside the Organization settings, you have different tabs.

### Settings[​](#settings "Direct link to Settings")

![Org interface description](/assets/images/interface-4-7659b7c98f6cc6308709ac30141f530a.png) ![Org interface description](/assets/images/interface-5-eb4536f7dbce05d25bc3f492da31b984.png)

## Metadata[​](#metadata "Direct link to Metadata")

You can see on the right a `Metadata` information rectangle that contains:

* `api_url`: The API URL of cycloid (useful when on premise installations.)
* `canonical`: The current organization canonical, this is a unique reference to the current organization. This is useful for API calls and scripting.
* `ci_team_name`: this is the current team uuid inside [concourse ci](https://concourse-ci.org "Concourse documentation"), our pipeline engine.

![](/img/organizations/metadata.png)

## Details[​](#details "Direct link to Details")

Here you can change the Organization name.

## Plan[​](#plan "Direct link to Plan")

This widget will display the number of available seats and your current licence status for cycloid.

![Org interface description](/assets/images/plan-b524368ab5ffca21486c90b76be0e940.png)

## Features[​](#features "Direct link to Features")

You can enable/disable some cycloid features here.

![Org interface description](/assets/images/features-e6668fa0c7b675bcc136d4886633744b.png)

## Terraform[​](#terraform "Direct link to Terraform")

This is where you can configure a terraform backend at org level for the [cycloid inventory](/reference/inventory/.md "Cycloid inventory").

![Org interface description](data:image/png;base64,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) ![Org interface description](/assets/images/terraform-2-32e1e22c24eeabe0516298a91d05c157.png)

## Appearance[​](#appearance "Direct link to Appearance")

This section allows you to change the theming of the current org.

![Org interface description](/assets/images/appearance-cb737e3f048cea02adf5063179cd9117.png)

tip

Creating different themes for your different orgs can help you differentiate more easily the org you are currently using

## Danger Zone[​](#danger-zone "Direct link to Danger Zone")

This is where you can delete an organization.

![Org interface description](data:image/png;base64,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)

danger

Resources created in an org won't be deleted automatically.

Please, ensure all your terraform resources are effectively deleted before deleting an organization.

## Workers[​](#workers "Direct link to Workers")

Here you can manage your org's workers.

see [workers sections](/reference/ci-cd-pipelines/concepts/workers/.md) for more information.

![Org interface description](/assets/images/interface-settings-worker-46b80ae68fe851c2b1519e1e73f1dde0.png)

## Members[​](#members "Direct link to Members")

Here you can manage the member of your org.

You can invite people using their email address and affect a [role](/reference/organizations/concepts/permissions.md) to them.

You can also select and delete org members.

![Org interface description](/assets/images/interface-settings-members-8369d2953e914fd8762ec7cd67a27262.png)

## Teams[​](#teams "Direct link to Teams")

Teams allow you to group users. Each team has a default role assigned to.

You can create and delete teams here.

![Org interface description](/assets/images/interface-settings-teams-ad0920f1c6e033f7fa38a2f3d36a3e64.png)

To affect a member to a team. Click on the team and you will access the team panel.

![Org interface description](/assets/images/interface-settings-teams-edit-3614fa09eed7e3c601f97df1d3f79a26.png)


---

# Licensing

## Overview[​](#overview "Direct link to Overview")

This documentation provides an overview of how licensing and subscriptions work within our product.

## Key Concepts[​](#key-concepts "Direct link to Key Concepts")

### License[​](#license "Direct link to License")

* **Definition**: The license is a hard limit set at the root organization (root org) level.
* **Function**: It defines the maximum number of unique users that can be registered in the database.
* **Implementation**: The license is a JSON Web Token (JWT) issued by Cycloid, ensuring data integrity and security.

### Subscription[​](#subscription "Direct link to Subscription")

* **Definition**: The subscription is a soft limit that applies a specific plan to an organization by assigning a specific amount of seats.

* **[Plans available](https://www.cycloid.io/pricing)**:

  <!-- -->

  * Platform teams
  * End-users
  * Free trial

* **Multi-plan Support**: Multiple subscriptions can exist simultaneously for the same organization. For example, one subscription can allocate 10 seats for platform teams, while another can allocate 20 seats for end-users.

* **Inheritance**: Subscriptions are inherited by default to sub-organizations, sharing the same number of seats.

* **Customization**: Specific subscriptions can be applied to sub-organizations, overriding the inherited subscription.

The **platform team** is responsible for designing the platform, as well as creating and maintaining all necessary automation. In contrast, **end-users** consume the platform as a self-service. Consequently, **end-users** have lighter usage and feature requirements compared to the **platform team**. At Cycloid, we believe it’s not fair to charge **end-users** the same price as **platform team users**. By differentiating pricing, you can scale platform usage efficiently without significant budget impacts.

## Inheritance and Subscription Sharing[​](#inheritance-and-subscription-sharing "Direct link to Inheritance and Subscription Sharing")

### Organizations and internal sub-organizations[​](#organizations-and-internal-sub-organizations "Direct link to Organizations and internal sub-organizations")

#### Description[​](#description "Direct link to Description")

* **OrgA**: Shares its subscriptions with **OrgA1** and **OrgA2**.
* **OrgA1 and OrgA2**: Can use free seats from **OrgA's** subscription.
* **Scenario**: If there is a free seat in OrgA's platform teams subscription, it can be assigned to a user in OrgA1 or OrgA2.
* **License**: As it applies to unique users in the subscriptions, there could be only 10 unique Platform Teams users in all those subscriptions. It will count as 10 seats in the license.

<!-- -->

### Managed Service Provider (MSP) Context[​](#managed-service-provider-msp-context "Direct link to Managed Service Provider (MSP) Context")

#### Description[​](#description-1 "Direct link to Description")

* **MSPOrg** is a Managed Service Provider company
* **AdminOrg**: 10 seats for their tech team (platform teams). Created under AdminOrg will share AdminOrg's subscription by default until a dedicated subscription is added.
* **Customer1Org** Subscription: Customer1 buys 30 licenses (end users).
* **Customer2Org** Subscription: Customer2 buys 50 licenses (end users).

<!-- -->

### Usage Calculation[​](#usage-calculation "Direct link to Usage Calculation")

* **Example**: If all seats are filled:

  <!-- -->

  * AdminOrg: 10 platform users
  * Customer1Org: 30 end users
  * Customer2Org: 50 end users

* **Total License Usage**: 90/100 users

This means you can only create a subscription (or extend an existing one) of 10 users for a new customer because of the hard limit of 100 users in the license. If you need to have more users available, you need to contact Cycloid to issue a new one.

## How to add/update/renew a subscription on organization[​](#how-to-addupdaterenew-a-subscription-on-organization "Direct link to How to add/update/renew a subscription on organization")

To add a subscription, you need to execute a command using our backend binary.

```
./youdeploy-http-api --config-file /opt/config.yml create-subscription --organization-canonical <ORGANIZATION_CAN> --members-count <NUMBER_INT>  --plan-canonical <end_users|platform_teams> --expiration-date <2026-09-14T14:00:13Z>
```

To update or renew a subscription, you have to add the `--overwrite` parameter to the command above.

## Why is there a License ?[​](#why-is-there-a-license- "Direct link to Why is there a License ?")

* **Purpose**: Ensures that the data cannot be modified or hacked, serving as the source of truth. It is only applied on the root organization.
* The license is implemented as a JWT token issued by Cycloid.

## How to acquire/renew a License ?[​](#how-to-acquirerenew-a-license- "Direct link to How to acquire/renew a License ?")

Contact our sales if you are already in contact with us, else use our [contact form on our website](https://www.cycloid.io/request-demo) to get the license. Then reach the root organization settings to add/renew the licence.

![](/img/organizations/renew-licence.png)

## Summary[​](#summary "Direct link to Summary")

* **License**: A hard limit at the root org level, defining the maximum number of users on Cycloid setup.
* **Subscription**: A soft limit with plans that can be inherited or customized for sub-orgs.


---

# Permissions

Cycloid platform include a fine tune policy based permission management. Each permission can have multiple policies that define allowed actions on entities.

Permissions can be attached to roles, members, teams and API\_keys. They are also scoped by organization.

note

This is a current limitation, since cycloid API tokens are scoped by organizations, you can't create an organization using the API (this includes the CLI too.).

This may evolve in the future.

## Policies[​](#policies "Direct link to Policies")

Define the scope for individual actions. Those actions can be of various type: creating a project, deleting a credential, reading roles, etc.

These policies can also be narrowed down to specific entities. So that, if you were to have multiple credentials, you could create a role containing policies only for a specific subset of credential. Thus allowing you to have a thinner control on who can do what.

![Policies](/assets/images/policies-bf07db4101bdebcd13c2b08c01e346c6.png)

If you want to target a specific Resource you can do it using the 'Specific resources' checkbox. You can there enter the specific 'canonical' of the resource or use `*` to make partial matches (e.g: `*-staging` will match all the resources ending with `-staging`)

![Policies](/assets/images/policies-propagate-192419a2174c1b6a7b33719e351d8ffd.png)

In entities with nested children you'll also find the "Propagate" button, which allows you to spread the actions down to all nested entities. This would obviously NOT spread specific resources, as they are specific of current entity.

### Manual Actions[​](#manual-actions "Direct link to Manual Actions")

If you want to customize even more the policies of the role you can use the "Manual Actions" which allows to customize the policies by writing the 'Action' and the 'Resource' manually:

* 'Action': Is the Policy code, can be found by selecting a Policy (ex: `organization:credential:create`)
* 'Resources': The full path to the Resource (ex: `organization:{org-canonical}:credential:{credential-canonical}`)

All of them can also use `*` or `**`:

* `*`: Anything in between separator (`:`) (ex: `organization:credential:*` allows all actions to credentials)
* `**`: Anything skipping separator (`:`) (ex: `organization:**` allows to do anything on the organization)

So you can create something like:

* `organization:credential:*` => `organization:{organization-canonical}:credential:cy-*`,`organization:{organization-canonical}:credential:*-staging`

Which will allow to do any action to the credential that start with `cy-` or end with `-staging`

Or

* `organization:project:**` => `organization:{organization-canonical}:project:{project-canonical}:**`

Which will allow access to any sub policy/action inside the specific `{project-canonical}`.

![Policies](/assets/images/policies-custom-2f02e8c46ebe74d3d73c943ca3d83501.png)

warning

If no resource is given, then the policy will be applied to all resources within the organization

## Roles[​](#roles "Direct link to Roles")

Inside Cycloid permissions are handled by roles which are an aggregation of policies. Those roles can then be assigned to a user at the organization level as a 'default role', or at a team level to provide extra permissions to a set of users within a team.

Cycloid maintain a set of default roles to cover most common use cases:

![Default role list](/assets/images/default-roles-2c301af23fdc3d506cdadc7ed7ae3a8a.png)

Roles will be available at both organization & team level. Which means that if you create a "Role A", that can for example manage any project and environments, it will be possible to apply it either to a team, to increase the permissions of those team members, or at the organization level to make it their default role when logging in - assuming they are not part of some teams.

Permissions are handled in an 'incremental way', there is no forbidding rules.

Either you have a permission to do an action or you do not. If you were given in a role the possibility to read project A, and in another one project B, you will end up with the permissions to read project A and B.

note

A special role exists, the 'admin' one, which once given provide access to any actions on any resources within the current organization.

![Roles](/assets/images/roles-dde5617cf7fc832e3d65271a6b978b63.png)

## Organization level[​](#organization-level "Direct link to Organization level")

The organization role is defined upon invitation of other members, it can be later on edited/updated by members who have access on it. To manage those members please click on the `Members` button on the *Organization settings* menu.

![Org members](/assets/images/org-members-3af04bd52d918c29bedc70b7380b4ab4.png)

It is also possible to invite multiple members with the same role:

![Org invite](/assets/images/org-invite-a73716810fd7defad3c20484547bfd6c.png)

## Teams level[​](#teams-level "Direct link to Teams level")

Teams are simply a gathering of people to which the same role(s) is applied.

This is meant to extend default permission of an organization member, and create logical group of people: because they work together, because there is some hierarchy, because of a temporary task to do, etc.

To create or manage teams, click on the `Teams` button of the panel:

![List team](/assets/images/list-team-1cafac31226c4fd6686dac4e0ca7cf5d.png)

If you want to create a new team click on the `Create a new team` button, or if you want to manage an existing one, click on it:

![Create team](/assets/images/create-team-da7b7e5affca1e9e973cf22aa2330734.png)

In this silly example the 'Cyclobot' account, which is admin of the organization, also gained the 'Organization Member' & 'Organization Owl' roles.


---

# Workers

CI/CD workers for pipelines in cycloid are scoped by organization.

![worker panel](/assets/images/interface-settings-worker-46b80ae68fe851c2b1519e1e73f1dde0.png)

You can add workers to the current org from this panel.

tip

See the [pipeline section](/reference/ci-cd-pipelines/.md) for more informations about workers.


---

# Open Source Software

Cycloid is built upon Open Source software. It is in our DNA and we contribute as much as we can to the OSS ecosystem.

This section list all the Open Source software made available by Cycloid.

| Name                                           | Description                                                |
| ---------------------------------------------- | ---------------------------------------------------------- |
| [InfraMap](/reference/oss/inframap.md)         | Generate infrastructure diagrams from your Terraform code. |
| [TerraCognita](/reference/oss/terracognita.md) | Migrate current infrastructure to infrastructure as code.  |
| [TerraCost](/reference/oss/terracost.md)       | Generate cost insight from your Terraform code.            |
| [Cycloid CLI](/reference/cli/.md)              | Cycloid command line interface.                            |
| [MCP Server](/reference/oss/mcp-server.md)     | Cycloid MCP Server.                                        |


---

# InfraMap

Related links

* [Github Repository & Readme](https://github.com/cycloidio/inframap)
* [InfraView](/reference/infraview/.md)

[YouTube video player](https://www.youtube-nocookie.com/embed/bLWmgDaEtHQ?si=IoAI1BlT7H9Q2B39)

InfraMap is a tool to generate infrastructure diagrams from your Terraform code or tfstate.

Use InfraMap to create your infrastructure diagrams in a single click (or add it as a step in your pipeline), using pruned infra-as-code that keeps all sensitive information safe. It’s a tool with the wow factor and is a genuine time-saver.

Think of InfraMap like [InfraView](/reference/infraview/.md)’s little sister - reading from tfstate or HCL files.

No Terraform? No problem - if you don't have Terraform, open-source tool [TerraCognita](https://github.com/cycloidio/terracognita)(/reference/oss/terracognita will generate the HCL and the tfstate file),

It automatically builds a graphical representation of your infrastructures without any input from you.

The end product is simpler than InfraView, but still offers the accessibility and ease of its big sister. Your InfraMap architecture diagram will open up your infra to non-technical team members, allowing you to identify points of error, troubleshoot faster, and ensure everything is up-to-date.

## Installation and usage[​](#installation-and-usage "Direct link to Installation and usage")

Please refer to the [GitHub repository's Readme](https://github.com/cycloidio/inframap) for more informations.


---

# Cycloid MCP Server

The [Cycloid Model Context Protocol (MCP) Server](https://www.cycloid.io/mcp-server) is a powerful tool that acts as a bridge, enabling Large Language Models (LLMs)—like those powering Claude, Cursor, or GitHub Copilot—to interact directly with your Cycloid instance. This allows you to leverage natural language to query your infrastructure, manage resources, and streamline your development workflows, all from your preferred interfaces.

The MCP server is a key component of our vision to **accelerate platform adoption with AI**. The MCP server is the first milestone of our future Cyclobot AI companion, that will easesthe journey of users on onboarding, configuration, centralization, usage, and call to actions.

***

## Why integrate LLMs with Cycloid?[​](#why-integrate-llms-with-cycloid "Direct link to Why integrate LLMs with Cycloid?")

The primary advantage of the Cycloid MCP Server is the ability to bring your Cycloid's data and actions into the conversational interfaces you already use. This offers several benefits:

* **Reduced Context Switching**: Access Cycloid information and initiate actions without leaving your IDE or chat tool.
* **Natural Language Interaction**: Use plain English (and other languages) to ask questions about your infrastructure, services, and deployments.
* **Enhanced Developer Experience**: Empower developers with self-service capabilities, reducing the burden on operations teams.

***

## Connect your client (IDE or MCP Client)[​](#connect-your-client-ide-or-mcp-client "Direct link to Connect your client (IDE or MCP Client)")

The MCP should be configured on your client (MCP client or Code Editor)

* Cursor
* VSCode
* Local MCP

warning

Since Cursor 1.6, the [Elicitation feature is broken](https://forum.cursor.com/t/mcp-elicitation-with-http-oauth-hangs-with-request-timed-out-error/133735/10). This breaks the `CYCLOID_BLUEPRINT_STACK_CREATE` tool until the issue is solved on a future update.

### Step 1: Install MCP Server[​](#step-1-install-mcp-server "Direct link to Step 1: Install MCP Server")

To install Cycloid MCP server on Cursor, it is simple as clicking on the button below:

![Install MCP Server](https://cursor.com/deeplink/mcp-install-light.svg)

### Step 2: Configure it[​](#step-2-configure-it "Direct link to Step 2: Configure it")

Just fill the Organization and API Key parameters, and click on the Install button

![](/img/mcp/cycloid-mcp-server-cursor.png)

To connect VSCode to Cycloid MCP server, follow these detailed steps. For more details, refer to the [official VS Code MCP documentation](https://code.visualstudio.com/docs/copilot/chat/mcp-servers).

### Step 1: Configure MCP Server Settings[​](#step-1-configure-mcp-server-settings "Direct link to Step 1: Configure MCP Server Settings")

1. Open VS Code settings
2. Search for "MCP: Open user configuration" (or follow the instructions on a workspace installation)
3. Add the server configuration using the appropriate configuration for your region:

* EU

```
{
  "servers": {
    "Cycloid MCP Server (HTTP)": {
      "url": "https://mcp.cycloid.io/mcp/",
      "type": "http",
      "headers": {
        "X-CY-ORG": "<your-organization-canonical>",
        "X-CY-API-KEY": "<your-api-key>"
      }
    }
  },
  "inputs": []
}
```

### Step 2: Start the MCP Server[​](#step-2-start-the-mcp-server "Direct link to Step 2: Start the MCP Server")

1. After adding the configuration, click on "Start" to initialize the MCP server

2. If you don't see the "Start" button, ensure:

   <!-- -->

   * Your VS Code version is updated to the latest version
   * MCP is enabled for your GitHub organization

### Step 3: Access the Cycloid Tools[​](#step-3-access-the-cycloid-tools "Direct link to Step 3: Access the Cycloid Tools")

1. Start a new chat session in VS Code
2. Click on the tools icon in the chat interface
3. You should now see Cycloid tools available for use

![](/img/mcp/cycloid-mcp-server-vscode.gif)

The server listen on HTTP, that means you can run it locally (check the Installation section below) Instead of pointing to the official MCP server urls, use a local endpoint:

```
{
  "mcpServers": {
    "Cycloid MCP Server (Local HTTP)": {
      "url": "https://127.0.0.1:8000/mcp/",
      "headers": {
        "X-CY-ORG": "<your-organization-canonical>",
        "X-CY-API-KEY": "<your-api-key>"
      }
    }
  }
}
```

***

## Host it On-Premise[​](#host-it-on-premise "Direct link to Host it On-Premise")

The Cycloid MCP Server is distributed as a Docker image, making it easy to run on any system with Docker installed. It is also available as a HTTP endpoint, hosted by us, pointing on our SaaS.

It's fairly easy to run it:

```
docker run -i --rm -e CY_API_URL=https://http-api.cycloid.io cycloid/cycloid-mcp-server:latest
```

The organization and API key will be sent by the client dynamically through HTTP header to the MCP Server. They act as authentication.

## Example Usage[​](#example-usage "Direct link to Example Usage")

Here are a few examples of how you can use the Cycloid MCP Server with a chat interface like Cursor, Windsurf, Claude, etc:

* "List all pipelines in my organization."
* "What are the last events ?"
* "Can you help me creating a stack using blueprints ?"

The MCP server will translate these natural language requests into API calls to your Cycloid instance and return the results in a human-readable format.

***

We hope this documentation helps you get started with the Cycloid MCP Server. If you have any questions or feedback, please feel free to open an issue on the [GitHub repository](https://github.com/cycloidio/cycloid-mcp-server).


---

# TerraCognita

Related links

* [Github Repository & Readme](https://github.com/cycloidio/terracognita)
* [GoDoc](https://godoc.org/github.com/cycloidio/terracognita)
* [Gitter chat](https://gitter.im/cycloidio/terracognita)
* [AUR package](https://repology.org/project/terracognita/versions)
* [Nix package](https://search.nixos.org/packages?show=terracognita\&from=0\&size=50\&sort=relevance\&type=packages\&query=terracognita)
* [Homebrew](https://formulae.brew.sh/formula/terracognita)
* [Roadmap](https://github.com/cycloidio/terracognita/issues/118)
* [Blog post - What is Terracognita ?](https://blog.cycloid.io/what-is-terracognita)

TerraCognita allows you to migrate your current cloud infrastructure to infrastructure-as-code. It quickly and automatically creates Terraform from all of your manually-provisioned resources, allowing them to be easily replicated by you and your cloud provider.

All you have to do is connect to your cloud, and let TerraCognita take care of the rest.

* Simplify migration to Terraform from manually provisioned infrastructures
* “Reverse engineers” Terraform from manual infras
* Keep configuration drift in check
* Makes it easy to apply policies

[YouTube video player](https://www.youtube.com/embed/PtJgf7AWBVA)

Imports your current Cloud infrastructure to an Infrastructure As Code [Terraform](https://www.terraform.io/) configuration (HCL) or/and to a Terraform State.

At [Cycloid](https://www.cycloid.io/), Infrastructure As Code is in the company DNA since the beginning. To help our new customers adopting this best practice, we decided to build Terracognita to convert an existing infrastructure on Cloud Infrastructure into Terraform code in an automated way, relying on Terraform providers built by the community.

We focused on AWS, GCP and Azure but Alibaba, Vmware and Openstack will be the next to be integrated.

We decided to Open Source this tool as we believe that it will help people to adopt IaC in an easy way. Cycloid provides this tool to let people import their infrastructure into [Cycloid's pipelines](https://www.cycloid.io/devops-framework), allow them to generate infrastructure diagram and manage all infra/application life cycle from a single interface.

If you are interested in contributing to TerraCognita or simply curious about what's next, take a look at the public [roadmap](https://github.com/cycloidio/terracognita/issues/118).

For a high level overview, check out the [What is Terracognita?](https://blog.cycloid.io/what-is-terracognita) blog post.

For more information, and the getting started informations, please check out the [Github Repository & Readme](https://github.com/cycloidio/terracognita).


---

# TerraCost

Related links

* [GitHub Repository](https://github.com/cycloidio/terracost)
* [PkgGoDev](https://pkg.go.dev/github.com/cycloidio/terracost)

## Overview[​](#overview "Direct link to Overview")

TerraCost automatically gives you insight into the total cost of your deployments - before you deploy them and without having to add them up manually.

This allows your to keep track of any impact that a change to infrastructure could have on finances. It offers visibility, transparency, and governance, meaning that it helps devs as much as it does managers.

It is an open-source project that can be audited, contributed to, and quickly integrated with any pipeline that uses Terraform.

* Automatically estimates your cloud costs before deployment
* Prevent accidental excessive cloud cost bills
* Uses your TerraForm plan to estimate costs
* Currently available through CLI, later via console interface
* Compare costs from deployment to deployment

Please refer to the [GitHub repository's Readme](https://github.com/cycloidio/terracost) for more informations.


---

# Projects

Projects are the main entity that allows you to use Cycloid.

![](/assets/images/projects-overview-bb7aa46c241761093922d148bbc321aa.png)

In Cycloid, a **project** provides a structured way to organize and manage related resources, workflows, and team activities. It serves as a container for all the assets and activities related to a specific initiative or product.

A **project** can contains multiples **environments** that can have multiples **components**

A **component** is an instance of a **stack**. Each component can have its own set of configurations, resources, and workflows to support different parts of the project deployment and management process.

An **environment** is a grouping of one or more components that share the same deployment variables. Environments are used to separate different stages of the project lifecycle, such as development, testing, and production.

![](/assets/images/project-e08dba6fc18b83f7ed0ba806f21ab074.png)

note

During project creation, you will be able to select a [config repository](/reference/config-and-catalog-repository/.md). ![](/assets/images/project-config-repo-3a38572e2a2593d379f3ef0640c55743.png)

The config repository will be used to store the configuration for each environment.


---

# Components

Components are instances of a [stack](/reference/stacks/.md) that are deployed to an environment. They are the building blocks of your platform.

Each environments can have multiple components allowing you to compose multiple stacks inside the same environment.

Since each component can use a different stack, you can leverage components and environments to group complex set of resources in one project.

![](/assets/images/project-components-3fb5a9fd93d5b0e79637763e1f32a066.png)

info

Using multiple components in the same env require stacks v4, see our [migration guide to components if required.](/cookbook/stacks-v4-migration/.md)

### Creating a component[​](#creating-a-component "Direct link to Creating a component")

You can access the component creation wizard directly from an environment's page, using the `Add component` button, or from the project overview tab, using the `Add new...` > `Add component` button, where you will be prompted to select the environment you want to add the component to.

![](/img/projects/components-add-button.gif)

The component creation wizard will guide you through the process of creating a new component. First you will be required to choose the stack you want your component to create an instance of. If your stack contains multiple usecases, you will be prompted to pick which one you want to use. You can then choose if you want to rename your component, that will default to the name of your stack, and add a description.

![](/img/projects/components-wizard-stack.gif)

From here, you can move to the final step, where you will fill out the configuration of your stack instance, and then be able to finish the creation of your component.

![](/img/projects/components-wizard-forms.gif)

warning

Please note that stacks that have not been upgraded to V4 are susceptible to naming conflicts.

For that reason, each environment can only have a maximum of one V1-3 stack. If you attempt to add a second one, stacks that have not been upgraded to V4 will be marked as incompatible.

For this reason, we reccomend upgrading your stacks to V4 as soon as possible, you can view the [upgrade guide here](/cookbook/stacks-v4-migration/.md).

![](/img/projects/components-wizard-stack-incompatible.png)

### Component settings[​](#component-settings "Direct link to Component settings")

* Component info: Allows you to change the component name and description, as well as view it's canonical and stack.

![](/img/projects/components-settings-info.png)

* Configuration: Redirects to the configuration of the component stack forms.

![](/img/projects/components-settings-configuration.png)

* Scheduling: Allows you to enable/disable the scheduling of the component. See more details in the [scheduling section](/reference/projects/concepts/scheduling.md).

![](/img/projects/components-settings-scheduling.png)

* IaC state management: This section allow you to configure a [Cycloid Terraform HTTP backend](/reference/inventory/.md#cycloid-global-terraform-http-backend) for the component. It will use the one configured at organization level by default.

![](/img/projects/components-settings-state-management.png)

* Danger zone: Allows you to delete the component.

warning

Please note that this is a permanent action and cannot be undone.

Resources created through pipelines will not be deleted automatically.

![](/img/projects/components-settings-danger-zone.png)

### Pipeline[​](#pipeline "Direct link to Pipeline")

The pipeline view is the hub where you can manage the current component's pipeline.

![](/img/projects/components-overview-pipeline.png)

In the top right corner, you can:

* **Pause the pipeline** or restart it
* **Edit the pipeline**: Ideal for temporary changes or tests. It edits only this specific running pipeline, and all changes will be reset if you reconfigure the component.
* **Refresh the pipeline** Refresh the current pipeline with the latest version of the pipeline template in the stack.

![](/img/projects/components-overview-pipeline-menu.png)

For more information, refer to the [pipeline section](/reference/ci-cd-pipelines/.md "Cycloid pipelines").

### Infrastructure[​](#infrastructure "Direct link to Infrastructure")

The infrastructure tab allows you to view a generated diagram of your infrastructure.

This feature requires some setup. Please see the [InfraView section](/reference/infraview/.md) for more information.

![](/img/projects/components-infrastructure.gif)

### Metrics[​](#metrics "Direct link to Metrics")

In the metrics tab, you can add different widgets to track KPIs accross you component's pipelines, like build history, average build time, and more.

![](/img/projects/components-metrics.png)

From here you may also set a widget as a favorite, for it to appear on your dashboard.

![](/img/projects/components-metrics-favorite.gif)

### Activity[​](#activity "Direct link to Activity")

This tab displays all [Cycloid events](/reference/events/.md "Cycloid events") related to the component.

![](/img/projects/components-activity.png)

### Configuration[​](#configuration "Direct link to Configuration")

The configuration tab allows you to fill out the form generated using Cycloid's [stackforms feature](/reference/stackforms/introduction.md "Stackforms introduction").

![](/img/projects/components-configuration.png)

The configuration of each component is stored in Git, within the [config repository](/reference/config-and-catalog-repository/.md) linked to the project.


---

# Environments

Environments within Cycloid are a collection of one or more components, that enable you to manage distinct configurations such as development, testing, and production, each with its own settings and resources.

Typical Environment Names:

* **Production**: Live software used by customers.
* **Staging/Pre-production**: For testing changes before pushing to production.
* **Dev/Test/Etc.**: Internal and development purposes.

These are common conventions, but you can name environments as you see fit. They serve to group components within a project.

![](/assets/images/project-e08dba6fc18b83f7ed0ba806f21ab074.png)

Most of the time, the environment name and project name in Cycloid are passed as input variables to infrastructure as code. This enables them to be used as tags on cloud resources, ensuring clear identification and organization of resources across different environments and projects.

## Create an environment[​](#create-an-environment "Direct link to Create an environment")

An environment belongs to a project. In an existing project, you can add a new environment by clicking on the button in the top right corner.

![](/img/projects/create-env-button.png)

Then choose a name, for your environment.

![](/img/projects/create-env-panel.png)

You can also change the icon color to make it easily identifiable.

![](/img/projects/create-env-pick-color.png)


---

# Interface

## Global[​](#global "Direct link to Global")

Project view is scoped on two levels: environment, and component. You can view the complete layout of your project from the **Overview** tab, and navigate to a specific environment or component from there.

![](/img/projects/interface-overview.png)

If you are viewing a complex project with many environments and components, you can toggle the view to the more compact table mode:

![](/img/projects/interface-table-view.png)

Once in the scope of an environment or component, you can see in the top left corner, next to the project name, the current environment or component you are viewing. Clicking on the arrows icon will open up the quick switch meny, allowing you to switch between environments or components, as well as create new ones.

![](/img/projects/interface-quick-switch.png)

You can also navigate directly to an environment from the project list page.

![](/img/projects/interface-project-card-env.png)

### Favorites[​](#favorites "Direct link to Favorites")

From the top right corner, you can mark a project as a favorite. This will add it to the list of projects that will be displayed on the dashboard page. This list is unique to each user.

![](/img/projects/interface-dashboard-favorite.png)

### Environment and project settings[​](#environment-and-project-settings "Direct link to Environment and project settings")

You can access a project's settings via the menu in the top right corner.

![](/img/projects/interface-project-menu-settings.png)

#### General section[​](#general-section "Direct link to General section")

Here you will be able to change the main settings of the project, such as:

* The name, icon and description
* The [config repository](/reference/config-and-catalog-repository/.md) where the configuration will be stored
* The owner of the project

> You will also be able to delete the project from this section. **Please note that this is a permanent action and cannot be undone. Resources created through pipelines will not be deleted automatically.**

![](/img/projects/interface-project-settings-general.png)

#### Logs section[​](#logs-section "Direct link to Logs section")

In this section, you will be able to configure a log provider, in order to display the logs for your environments. Currently supported are AWS CloudWatch and Elasticsearch.

![](/img/projects/interface-project-settings-logs.png)

#### Environment settings[​](#environment-settings "Direct link to Environment settings")

For each of the environments in your project, you can access the settings by clicking the environment names in the left sidebar. From here, you will be able to change the name and color of an environment (*please note this only concerns the displayed name, and not the environment's canonical, which cannot be changed*).

> You will also be able to delete the environment from this section. **Please note that this is a permanent action and cannot be undone. Resources created through pipelines will not be deleted automatically.**

![](/img/projects/interface-project-settings-environment.png)

## Activity[​](#activity "Direct link to Activity")

This tab displays all [Cycloid events](/reference/events/.md "Cycloid events") related to this project.

![](/img/projects/interface-activity.png)


---

# Logs

Applications and infrastructure logs stored in a compatible backend can be displayed in Cycloid, offering a convenient and centralized way to monitor your application after deployment.

Cycloid logs allow you to view logs from all your servers across all environments, organized into user-defined groups. You can apply filters and search to log entries to find specific patterns or servers.

![](/assets/images/interface-logs-23b1d4bcc8fd8042c64e7029f28f122e.png)

## Prerequisites[​](#prerequisites "Direct link to Prerequisites")

To display logs in Cycloid dashboards, use a compatible log backend such as [Elasticsearch](https://github.com/elastic/elasticsearch) or [AWS CloudWatch Logs](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/WhatIsCloudWatchLogs.html).

Your application or infrastructure logs need to be sent to the chosen log backend. This can be done directly from your application or by using a log collector agent such as Logstash or Fluentd. You can refer to our Ansible role for configuring a [Fluentd agent with Cycloid](https://github.com/cycloidio/ansible-fluentd).

## Configuration[​](#configuration "Direct link to Configuration")

Logs configuration is made in project Settings, under logs section.

![](/assets/images/interface-config-logs-ea6f8dfce8fe025db8df52f073802a16.png)

### With ElasticSearch[​](#with-elasticsearch "Direct link to With ElasticSearch")

* Select ElasticSearch

![](/assets/images/interface-config-logs-es-8e2fcea2582d5438bf45c009788cf3df.png)

* Then configure the access and mapping for each ElasticSearch environment source that must be used to search for logs entries

![Logs es config](/assets/images/logs_es_config-be28d13dcd4b5d5e56daeed6a93ba839.png)

### With AWS CloudWatch Logs[​](#with-aws-cloudwatch-logs "Direct link to With AWS CloudWatch Logs")

* Select AWS CloudWatch and enter the AWS credentials to use.

![AWS CloudWatch Logs Configuration](/assets/images/interface-config-logs-aws-6f25e1f31b2df14324328680c143d6cb.png)

Logs are directly fetched from [AWS CloudWatch](https://aws.amazon.com/cloudwatch/). Logs must be stored in [Log Groups](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/CloudWatchLogsConcepts.html) following the naming format:

* `$PROJECT_$ENV`

This log group can contain multiple log streams. Each log stream will be displayed in the Cycloid console as a different source. Typically, a log stream is created for each log file type (e.g., syslog, access.log).

By default, no Log Groups or Log Streams are created for you; it is your responsibility to create and feed them with logs from your systems, jobs, applications, etc. You can use services like Fluentd or Logstash to help format logs intended for AWS CloudWatch.


---

# Metrics

In the **Metrics** tab, you can view and configure Key Performance Indicators (KPIs) to gain insights into your pipelines, jobs, deployments, code coverage, and more.

Metrics data can come directly from pipelines or Cycloid events.

![Metric Tab](/assets/images/interface-metrics-33a235306aeb76c4c957dcddc9940db7.png)

The following sections will provide more information on the different data sources and the various ways to present them.

## Datasources[​](#datasources "Direct link to Datasources")

As previously mentioned, some KPIs are based on **pipelines**, while others are based on **events**.

Pipeline-based KPIs require only configuration and will work out of the box.

Event-based KPIs also need configuration but require you to send events to Cycloid to build data. Events can be sent using API calls or through our CLI.

## Add a metric[​](#add-a-metric "Direct link to Add a metric")

You can add metrics directly through the Cycloid console. Navigate to your project, select the component you wish to view metrics for, and click on the `Metrics` tab. Then, click the `Add metric` button. This will bring up a list of possible KPIs. Select the desired KPI, and a specific popup will appear to guide you through the configuration process.

![](/img/add-metric-menu.png)

Another way to configure metrics for your project is by using [Cycloid's CLI](/reference/cli/.md). Here are some examples of how to use the CLI:

```
# Configure a build_history kpi on our test project
cy kpi create --name "Job test history" --org test \
--type build_history --widget history --project test --env test --job test

# Configure a time_to_release kpi on our test project
cy kpi create --name "Time to release" --org test \
--type time_to_release --widget line --project test --config '{"envs": ["dev", "staging", "prod"]}'
```

## List of Available KPIs[​](#list-of-available-kpis "Direct link to List of Available KPIs")

There are currently five available KPIs, grouped into two data source types: **pipelines** and **events**. Some KPIs can be displayed in different ways using various widgets (e.g., build\_history KPI). This flexibility allows you to create additional metrics to present data from different perspectives.

| Name                   | Type              | data Source | Widgets allowed | Description                                                                                                                    |
| ---------------------- | ----------------- | ----------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| **Build average time** | `build_avg_time`  | *pipelines* | bars            | gives insight on the average build time of a job                                                                               |
| **Build frequency**    | `build_frequency` | *pipelines* | line            | shows how frequently a job is being triggered                                                                                  |
| **Build history**      | `build_history`   | *pipelines* | history, pie    | provides longer job history and better representation                                                                          |
| **Code coverage**      | `code_coverage`   | *events*    | doughnut        | shows code's coverage as well as evolution                                                                                     |
| **Time to release**    | `time_to_release` | *events*    | line            | indicates how long releases spend in each environment. (CLI config attribute required `--config '{"envs": ["env1", "env2"]}'`) |

Events Data Sources

As mentioned earlier, to use KPIs based on `events` data sources, you need to send those events to populate KPI data. Events can be sent using our CLI or API calls from a pipeline, external tools, or your own application.

See the Events-Based KPIs section below for more details

### Look[​](#look "Direct link to Look")

| KPI types             | Widget     | Render                                   |
| --------------------- | ---------- | ---------------------------------------- |
| **build\_avg\_time**  | *bars*     | ![batb](/img/widget-build-time.png)      |
| **build\_frequency**  | *line*     | ![bfl](/img/widget-build-frequency.png)  |
| **build\_history**    | *history*  | ![bhh](/img/widget-build-history.png)    |
| **build\_history**    | *pie*      | ![bhp](/img/widget-success-failure.png)  |
| **code\_coverage**    | *doughnut* | ![ccd](/img/widget-code-coverage.png)    |
| **time\_to\_release** | *line*     | ![ttrl](/img/widget-time-to-release.png) |

### Specifications[​](#specifications "Direct link to Specifications")

#### KPI `time_to_release`[​](#kpi-time_to_release "Direct link to kpi-time_to_release")

The **Time to release** configuration corresponds to the order of environments, from the first to the latest.

For example, if you have 3 environments: `production`, `preproduction` and `development`, you'd set the configuration to: `development, preproduction, production`. Which indicates the branch order that your features are going through, which will help to identify extra time spent at every stage.

Please note, that the version is irrelevant to establish if a version has been released or not. That is because a version could be anything: version, timestamp, tags, commit id, etc.

Instead the chronology is used to be able to identify if something has been deployed or not. This is why if you have in your list of events:

1. dev - v1 at t
2. dev - v2 at t+1
3. prod - v1 at t+2

The dev v1 and v2 will be considered both released, because the deployment of prod came after (no matter the version number). However if you had the event of prod v1 deployment before dev v2 deployment, then dev v2 wouldn't be considered released.

## Events-Based KPIs[​](#events-based-kpis "Direct link to Events-Based KPIs")

As described earlier, some KPIs use Cycloid events as data sources, meaning you need to send events to Cycloid to populate data for these KPIs.

For example, the "Code Coverage" metric relies on data from Cycloid events. Typically, when writing an application, tools or commands generate the code coverage percentage during unit tests in a pipeline. To report this to the KPI event-based data source, you need to send it as a Cycloid event in a specific format.

Usually, customers run their application tests to obtain the code coverage percentage in a pipeline, then create a post-task using the Cycloid CLI to send an event reporting the code coverage.

Tip

If you're unfamiliar with Cycloid events, take a look at our [events page](/reference/events/.md) to learn how to send events through your pipelines. You can also check out [our CLI](/reference/cli/.md) if you prefer to do that from scripts or from your favorite shell.

### Events Formats[​](#events-formats "Direct link to Events Formats")

To be properly consumed by the KPIs, events must follow a specific JSON format:

| KPI Type            | Body                                  | Required Tags                                                                         |
| ------------------- | ------------------------------------- | ------------------------------------------------------------------------------------- |
| **Code Coverage**   | `{"coverage": 42.001}`                | `[{"key": "kpi", "value": "code_coverage"}, {"key": "project", "value": "<name>"}]`   |
| **Time to Release** | `{"env": "<name>", "version": "<v>"}` | `[{"key": "kpi", "value": "time_to_release"}, {"key": "project", "value": "<name>"}]` |

Important

Ensure the body/tags are valid JSON using an online JSON validator or CLI commands.

Here are some examples of how you can create these events via Cycloid's CLI:

```
# KPI time_to_release
cy  --org test event create --tag kpi=time_to_release --title "Release" \
--tag project=test --message '{"env": "dev", "version": "v1"}'

# KPI code_coverage
cy  --org test event create --tag kpi=code_coverage --title "Coverage" \
--tag project=test --message '{"coverage": 60.10}'
```

## Frequent Questions[​](#frequent-questions "Direct link to Frequent Questions")

### I've configured my KPIs but the data is empty, what can I do?[​](#ive-configured-my-kpis-but-the-data-is-empty-what-can-i-do "Direct link to I've configured my KPIs but the data is empty, what can I do?")

If the KPIs configured are based on events, you have to start sending events to feed the KPI. If the KPIs configured are based on pipeline, then the data is imported every day.


---

# Scheduling

The scheduling feature allows you to optimize costs by automatically starting and stopping cloud resources for specific components.

For example, if you have a staging environment, with components running on AWS that your employees use only during working hours, you can define start and stop hours for the cloud resources using the scheduling feature.

Additionally, you can manually trigger the start or stop of a component by clicking the play/stop buttons in the project/environment view.

![](/assets/images/scheduling-manual-trigger-4787ac571f2d0dce2328af08ad983ed1.png)

## Introduction[​](#introduction "Direct link to Introduction")

All start/stop scheduling automation is based on a pipeline engine. When you **configure scheduling** for a specific component on the console, a **start-stop pipeline** is automatically created from one of our templates.

The pipeline automatically triggers a **start/stop job** based on the configured schedule. This job makes the appropriate **Cloud provider API** calls to stop compatible resources. For example, the AWS pipeline handles:

* RDS databases: Stops the database
* EC2 instances: Stops the instances
* ASG (autoscaling groups): Reduces the number of instances to 0

To identify the Cloud resources, we filter them based on tags set on resources. Please follow the Prerequisites section to ensure your cloud resources are tagged correctly.

## Prerequisites[​](#prerequisites "Direct link to Prerequisites")

To be compatible with this feature, ensure the cloud provider resources are created with the following tags:

* **component** = `Name of the component in Cycloid`
* **env** = `Name of the environment in Cycloid`
* **project** = `Name of the project in Cycloid`
* **cycloid.io** = `true`

## Quickstart[​](#quickstart "Direct link to Quickstart")

To configure scheduling, access your component settings by clicking on the settings icon:

![](/img/projects/scheduling-component-menu.png)

Then, click on the **Scheduling** section. You can either configure the start and stop timings with frequency and preferred times or directly insert a [Unix cron format](https://en.wikipedia.org/wiki/Cron) by selecting the 'Cron' tab.

![](/assets/images/scheduling-options-modal-30bae513c30089c12fff973ee02a4432.png)

Once configured, you can view and customize the created pipeline by clicking on "View start-stop pipeline" in the environment settings.

![](/assets/images/scheduling-config-section-f0f202e27ce80523026e65db8523263a.png)

The generated pipeline will look like this for AWS:

![](/assets/images/scheduling-start-stop-pipeline-d8e19f44667cc50fc41661a78edb5172.png)

Each job handles different cloud provider resources (RDS, EC2, ASG). You can edit the pipeline to add more resources or custom pre-post tasks to the start/stop workflow.


---

# Migrating a Component from One Project to Another

In Cycloid, it's possible to move a component from one project to another. In most cases, it's easier and cleaner to simply delete and recreate the component. However, in specific scenarios, you may need to force the migration of an existing component.

Important

This documentation requires platform administrator access and must be executed by an administrator

## Preparation[​](#preparation "Direct link to Preparation")

First, identify the component you want to migrate and ensure that the **target project and environment already exist**.

Log in to the Cycloid Console and navigate to the **settings page** of the component you want to migrate.

* Click on **Terraform Remote Backend** and save the following information:

```
EXTERNAL_BACKEND_ID=7737  # Extract this ID from the component URL
```

## CLI Migration[​](#cli-migration "Direct link to CLI Migration")

Open a terminal and use the Cycloid CLI to move the component between projects.

```
# Adapt the variables to your platform context
export CY_API_URL=https://http-api.cycloid.io
export CY_ORG=cycloid-sandbox
export CY_API_KEY="....."

cy login

cy comp migrate \
  --project project1 \
  --env prod1 \
  --component dummy \
  --new-project project2 \
  --new-env prod2 \
  --new-canonical dummy
```

At this stage, the component and its Git configuration have been successfully moved to the new project. However, there's one final step: migrating the **Terraform remote backend** associated with the component, to preserve inventory items and the Terraform state.

## Backend Reassignment[​](#backend-reassignment "Direct link to Backend Reassignment")

First, gather the necessary information:

```
export PROJECT=project2         # Target project canonical
export ENV=prod2                # Target environment canonical
export COMPONENT=mycomponent    # Canonical name of the migrated component

cy comp get --project $PROJECT --env $ENV --component $COMPONENT -o json | jq -r '.id | "SET @component_id = \(.);"'
cy project get --project $PROJECT -o json | jq -r '.id | "SET @project_id = \(.);"'
cy environment get --project $PROJECT --env $ENV -o json | jq -r '.id | "SET @env_id = \(.);"'
```

Then, connect to the Cycloid MySQL database and run the following SQL query to reassign the external backend to the new component:

```
-- From the console URL (saved earlier)
SET @external_backend_id = ...;

-- From the CLI commands above
SET @project_id = ...;
SET @env_id = ...;
SET @component_id = ...;

UPDATE external_backends
SET
    project_id = @project_id,
    environment_id = @env_id,
    component_id = @component_id
WHERE id = @external_backend_id
LIMIT 1;
```

## Final Step[​](#final-step "Direct link to Final Step")

Finally, **trigger a refresh pipeline** or **reapply StackForms** to ensure the pipeline reflects the restored values and configuration.


---

# Migrating an Environment from One Project to Another

Legacy

This doc is based before component layer feature. Main workflow could be applied with components. But few things need to be adapted.

There are several reasons why you might want to rename a project and its environments, such as better reflecting its purpose, aligning with naming conventions, or accommodating organizational changes.

While you can rename a project in the console, its canonical name—used in the console URL and for [Cycloid special variables](/reference/stacks/concepts/templating.md#special-variables) unchanged. The same applies to environment names. To achieve a complete rename of a project and its environments, we recommend migrating environments to a new project by following this procedure.

The key principle of this migration is to **create a new project and transfer the environments** to it.

## With Cycloid CLI[​](#with-cycloid-cli "Direct link to With Cycloid CLI")

You can perform a complete renaming using the [Cycloid CLI](/reference/cli/.md)

Important

Before starting, be sure to pause the environment pipeline to prevent any modifications during the process.

In this example, we will rename the `project/environments` **From**

```
project: oldproject
environment: oldenv
```

**To**

```
project: newproject
environment: newenv
```

### Authentification[​](#authentification "Direct link to Authentification")

To create a new project and transfer the environments, we use the Cycloid CLI. The CLI requires authentication with the Cycloid API via an API key, which can be set using the following environment variables:

```
export CY_API_KEY=apikey_from_console
export CY_ORG=cycloid
```

### Create a new project[​](#create-a-new-project "Direct link to Create a new project")

The first step is to create a **new project** with the **same configuration** as the one you want to rename.

```
# List existing projects
cy project list -o json | jq -r  .[].canonical
foo
oldproject
bar

# Get project details from the oldproject
OLD_PROJECT=oldproject
OLD_PROJECT_DETAIL=$(cy project get -o json --project $OLD_PROJECT)

# Create the new project
NEW_PROJECT=newproject
cy project create \
  --name $NEW_PROJECT \
  --description "$(echo $OLD_PROJECT_DETAIL | jq -r .description)" \
  --owner "$(echo $OLD_PROJECT_DETAIL | jq -r .owner.username)"\
  --stack-ref $(echo $OLD_PROJECT_DETAIL | jq -r .service_catalog.ref) \
  --config-repo $(echo $OLD_PROJECT_DETAIL | jq -r .config_repository_canonical)
```

### Re-create and rename previous environments[​](#re-create-and-rename-previous-environments "Direct link to Re-create and rename previous environments")

List the environments from the old project and recreate them with the new name.

```
# List existing environments
echo $OLD_PROJECT_DETAIL | jq -r .environments[].canonical
oldenv
test

# Get environment details from the oldenv
OLD_ENV=oldenv
ENV_DETAIL=$(cy project get-env-config -p $(echo $OLD_PROJECT_DETAIL | jq -r .canonical) -e $OLD_ENV)
OLD_ENV_USECASE=$(echo $OLD_PROJECT_DETAIL | jq -r '.environments[] | select(.canonical == "'$OLD_ENV'") |.use_case')

# Create the new environment
NEW_PROJECT=newproject
NEW_ENV=newenv
echo $ENV_DETAIL | cy project create-stackforms-env --project $NEW_PROJECT --env $NEW_ENV -f - --use-case $OLD_ENV_USECASE --update
```

You can, of course, use a loop to recreate all existing environments

```
OLD_PROJECT=oldproject
OLD_PROJECT_DETAIL=$(cy project get -o json --project $OLD_PROJECT)
NEW_PROJECT=newproject
IFS=$'\n'
for env in $(echo $OLD_PROJECT_DETAIL | jq -c .environments[]);do
  OLD_ENV=$(echo $env | jq -r .canonical)
  ENV_DETAIL=$(cy project get-env-config -p $(echo $OLD_PROJECT_DETAIL | jq -r .canonical) -e $OLD_ENV)
  OLD_ENV_USECASE=$(echo $env | jq -r .use_case)

  # Change to the new name
  NEW_ENV="${OLD_ENV}-new"
  echo $ENV_DETAIL | cy project create-stackforms-env --project $NEW_PROJECT --env $NEW_ENV -f - --use-case $OLD_ENV_USECASE --update
done
```

### Move the tfstate file to the new environment location (Optional)[​](#move-the-tfstate-file-to-the-new-environment-location-optional "Direct link to Move the tfstate file to the new environment location (Optional)")

When using Terraform, you might need to move the previous tfstate file to the new environment location to maintain consistency and ensure that all previously created resources are track and managed in the new environment.

To access the tfstate from the [Cycloid Terraform HTTP backend](/reference/inventory/concepts.md#how-manually-upload-tfstate-file-using-our-api), you need to get the JWT token from the external-backend.

```
OLD_PROJECT=oldproject
OLD_ENV=oldenv
NEW_PROJECT=newproject
NEW_ENV=newenv

# Get the JWT_TOKEN from the OLD_ENV
OLD_JWT_TOKEN=$(cy external-backend list -o json | jq -r '.[] | select( .project_canonical == "'$OLD_PROJECT'" and .environment_canonical == "'$OLD_ENV'") | .jwt')

# Get the JWT_TOKEN from the NEW_ENV
NEW_JWT_TOKEN=$(cy external-backend list -o json | jq -r '.[] | select( .project_canonical == "'$NEW_PROJECT'" and .environment_canonical == "'$NEW_ENV'") | .jwt')

# Retrieve the tfstate from `oldenv`
export API_URL=https://http-api.cycloid.io
curl "${API_URL}/inventory?jwt=${OLD_JWT_TOKEN}" -X GET -H 'content-type: application/json' > /tmp/$NEW_PROJECT-$NEW_ENV

# And migrate it to `newenv`
curl "${API_URL}/inventory?jwt=${NEW_JWT_TOKEN}" -X POST -H 'content-type: application/json' -d @/tmp/$NEW_PROJECT-$NEW_ENV
rm /tmp/$NEW_PROJECT-$NEW_ENV
```

You can, of course, use a loop to move the tfstate file to the new environment location

```
OLD_PROJECT=oldproject
OLD_PROJECT_DETAIL=$(cy project get -o json --project $OLD_PROJECT)
NEW_PROJECT=newproject
IFS=$'\n'
for env in $(echo $OLD_PROJECT_DETAIL | jq -c .environments[]);do
  OLD_ENV=$(echo $env | jq -r .canonical)
  # Change to the new name
  NEW_ENV="${OLD_ENV}-new"

  # Get the JWT_TOKEN both envs
  OLD_JWT_TOKEN=$(cy external-backend list -o json | jq -r '.[] | select( .project_canonical == "'$OLD_PROJECT'" and .environment_canonical == "'$OLD_ENV'") | .jwt')
  NEW_JWT_TOKEN=$(cy external-backend list -o json | jq -r '.[] | select( .project_canonical == "'$NEW_PROJECT'" and .environment_canonical == "'$NEW_ENV'") | .jwt')

  # Retrieve the tfstate from `oldenv`
  export API_URL=https://http-api.cycloid.io
  curl "${API_URL}/inventory?jwt=${OLD_JWT_TOKEN}" -X GET -H 'content-type: application/json' > /tmp/$NEW_PROJECT-$NEW_ENV

  # And migrate it to `newenv`
  curl "${API_URL}/inventory?jwt=${NEW_JWT_TOKEN}" -X POST -H 'content-type: application/json' -d @/tmp/$NEW_PROJECT-$NEW_ENV
  rm /tmp/$NEW_PROJECT-$NEW_ENV
done
```

Important

Be cautious when using Cycloid Project or Environment variables to name your cloud provider Terraform resources, as this may result in unintended changes being applied.


---

# Stack Blueprints

<!-- -->

Templates allows stack creators to quickly start writing a stacks by selecting a pre-defined Blueprint.

Blueprint serve as a starting point for creating stacks and can be used to introduce features, enforce design patterns, and establish best practices for your teams.

Cycloid provide a set of pre-defined blueprints to use common technologies like terraform and ansible inside cycloid platform, you can start using them to kickstart your first stacks in Cycloid.

Writing a blueprint can be a way to streamline stack developpement inside your orgnization.

## Quickstart[​](#quickstart "Direct link to Quickstart")

### Using a Blueprint[​](#using-a-blueprint "Direct link to Using a Blueprint")

When creating a stack within the Cycloid UI, you can start from a blueprint by following these steps:

* Navigate to the Stacks section in the Cycloid UI.
* Click on the Create Stack button.
* Select the 'Create from Blueprint' option.
* In the stack creation form, select the desired blueprint from the available options.
* Customize the stack parameters and settings as needed.
* Click Create Stack to create the stack using the selected blueprint.

Voilà, your stack is created! Most often, the generated stack contains a README.md file that explains how to use it, and eventually what needs to be edited.

Using a blueprint provides a foundation for your stack, including pre-configured resources, configurations, and other relevant settings. It enables you to start working on your stack more efficiently, saving time and effort.


---

# Concepts

## Writing your own blueprints[​](#writing-your-own-blueprints "Direct link to Writing your own blueprints")

Cycloid allows you to create custom stack blueprints tailored to your specific use cases.

### Blueprint structure[​](#blueprint-structure "Direct link to Blueprint structure")

A blueprint is **nearly identical to a stack**, with similar structure and files. It needs a `.cycloid.yml` file, and may contain a pipeline, Terraform modules, Ansible playbooks, a README.md file and any other relevant files.

Blueprint's `.cycloid.yml` files must have the `template` attribute set to `true`.

For example, given the following directory structure:

```
.
├── .cycloid.yml
├── .forms.yml
├── README.md
├── pipeline
│   ├── pipeline.yml
│   └── variables.sample.yml
└── terraform
    └── provider.tf
```

With the following `.cycloid.yml` file:

```
version: "3"

name: Blueprint                         # The name of the blueprint
canonical: blueprint-canonical          # The unique canonical of the blueprint
author: '($> .stack_author <$)'           # The author of the blueprint
description: 'A blueprint description.' # The blueprint description
template: true                         # The attribute that differentiate a blueprint from a stack.

config:
  default:
    name: 'Default'
    pipeline:
      pipeline:
        path: 'pipeline/pipeline.yml'
      variables:
        path: 'pipeline/variables.sample.yml'
        destination: '($ .config_root $)/pipeline/variable.yml'
```

Blueprints, just like stacks, need to be imported in catalog repositories. You may have catalog repositories dedicated for blueprints, or even have blueprints and stacks together the same repository.

### Templating language[​](#templating-language "Direct link to Templating language")

Cycloid uses the Go [text/template package](https://pkg.go.dev/text/template) with [sprig functions](https://github.com/Masterminds/sprig) functions to render the blueprint files.

The usage is the same as [kubernetes helm template language](https://helm.sh/docs/chart_template_guide/functions_and_pipelines/).

The fondamental difference is the **blueprint template delimiter is `($>` `<$)` instead of `{{` `}}`.**

This is to ensure the blueprint templates does not collide with other templating engines (e.g. ansible, or our stack templating).

Be careful !

We also support [stack templating](/reference/stacks/concepts/templating.md), using the same templating language, but with a different delimiter `($` `$)`.

Stack templating with `($` `$)` is made to add templates on an existing stack to help create complex logic.

Blueprints templates with `($>` `<$)` are used to **create a new stack with pre-defined files**.

Be sure to differenciate the two types of templates.

### Variables[​](#variables "Direct link to Variables")

Several variables are exposed and can be used within your stack blueprints:

<!-- -->

| Variable name     |  Description                                                           |
| ----------------- | ---------------------------------------------------------------------- |
| `api_url`         | The URL of the Cycloid API                                             |
| `stack_author`    | The username of the user who creates the stack                         |
| `stack_canonical` | The stack canonical filled in by the user                              |
| `stack_path`      | The path of the generated stack in the catalog repository              |
| `stack_usecase`   | The key of the selected use case                                       |
| `scs_canonical`   | The canonical of the target catalog repository                         |
| `scs_cred_path`   | The path in Vault of the target catalog repository credential          |
| `scs_cred_type`   | The type of the target catalog repository credential (`ssh` or `http`) |

### README files[​](#readme-files "Direct link to README files")

A blueprint may contain a `README.md` file, which will be copied over to the stack. Upon creating a stack from a blueprint, users will be redirected to the stack details page where the stack README is displayed.

It's a good idea to rely on this README to guide users on how to use and manipulate their stack.

### Multi use-cases blueprints[​](#multi-use-cases-blueprints "Direct link to Multi use-cases blueprints")

Like stacks, blueprints may include multiple use-cases to cover a variety of scenarios.

When selecting a multi use-cases blueprint, users will have to select the desired use-case to use in their stack.

The output stack will only contain the selected use-case, making the stack easier to understand.

Limitation

Blueprints cannot generate multi use-cases stacks. Only a single use-case will be kept when generating a stack.

When a blueprint use-cases are very similar, with only small differences, they can be combined in a single files by using templating to handle the differences. See this example `provider.tf` file:

```
variable "org" {}
variable "project" {}
variable "env" {}
variable "component" {}

($>- if ne .stack_usecase "aws" <$)
provider "aws" {
  access_key = var.aws_cred.access_key
  secret_key = var.aws_cred.secret_key
  region     = var.aws_region
  default_tags {
    tags = {
      "cycloid.io" = "true"
      org          = var.org
      project      = var.project
      env          = var.env
      component    = var.component
    }
  }
}
variable "aws_cred" {}
variable "aws_region" {
  description = "AWS region to launch servers."
  default     = "eu-west-1"
}

($>- else if eq stack_usecase "gcp" <$)
terraform {
  required_providers {
    google = {
      source  = "google"
      version = "~> 2.18.0"
    }
  }
}
provider "google" { project = var.gcp_project }
variable "gcp_project" { default = "cycloid-demo" }
variable "gcp_zone" { default = "europe-west1-b" }
($>- end <$)
```

But in other situations, use-cases can be widely different and require specific files.

In this scenario, use-case specific files can be organized in folders named after the use-case keys (as defined in `.cycloid.yml`), placed in a `extra-template` directory located at the root of the blueprint.

Given the following `.cycloid.yml` definition, where we define two use-cases:

```
version: "3"

name: Blueprint                         # The name of the blueprint
canonical: blueprint-canonical          # The unique canonical of the blueprint
author: '($> stack_author <$)'          # The author of the blueprint
description: 'A blueprint description.' # The blueprint description
template: true                          # The attribute that differentiate a blueprint from a stack.

config:
  aws: # <- this is the use-case key
    name: 'AWS'
    description: 'An example use-case'
    pipeline:
      pipeline:
        path: 'foo-pipeline.yml'
      variables:
        path: 'foo-variables.sample.yml'
        destination: '($ .config_root $)/pipeline/variables.yml'
  azure:
    name: 'Azure'
    description: 'Another example use-case'
    pipeline:
      pipeline:
        path: 'bar-pipeline.yml'
      variables:
        path: 'bar-variables.sample.yml'
        destination: '($ .config_root $)/pipeline/variables.yml'
```

And considering we need two entirely different pipelines for the two use-cases, we can use the following blueprint directory structure:

```
.
├── .cycloid.yml
├── .forms.yml
├── README.md
└── extra-templates
    ├── aws # Folder name matches the use-case key
    │   ├── foo-pipeline.yml
    │   └── foo-variables.sample.yml
    └── azure # Folder name matches the use-case key
        ├── bar-pipeline.yml
        └── bar-variables.sample.yml
```

When creating a stack with the use-case `foo`, files and folders placed under `extra-templates/foo/` will be moved in the blueprint root directory, and the `extra-templates` directory removed. Files from `extra-templates/foo/` will overwrite any file with the same name already present in the blueprint root directory.

Following our previous example, creating a stack with the `foo` use-case would give us the following directory structure:

```
.
├── .cycloid.yml
├── .forms.yml
├── README.md
├── foo-pipeline.yml
└── foo-variables.sample.yml
```

And here is what users will see when selecting this blueprint:

![Blueprint use case choice interface.](/assets/images/use_case_choice-4fe686142e2f874293c21a3c6d8fee07.png)

## Enabling Cycloid blueprints[​](#enabling-cycloid-blueprints "Direct link to Enabling Cycloid blueprints")

Cycloid maintains a [set of basic blueprints](https://github.com/cycloidio/bootstrap-stacks/tree/master) that serve as a starting point for writing your first stacks.

These blueprints showcase minimal and well-documented examples, providing a solid foundation for building your own stacks and exploring the capabilities of Cycloid.

To access Cycloid blueprints, create a catalog repository configured with the `https://github.com/cycloidio/stack-blueprints.git` URL on the `master` branch. This repository is public and doesn't require credentials.

Once the configuration is complete, you will be able to see and select Cycloid blueprints when creating stacks in the UI. These blueprints provide a foundation for building your own stacks and exploring the capabilities of Cycloid.

note

If you are unable to see Cycloid blueprints, ensure that your catalog repository is properly configured and linked to the correct GitHub repository.


---

# Reference

## Variables[​](#variables "Direct link to Variables")

Several variables are exposed and can be used within your stack blueprints:

<!-- -->

| Variable name     |  Description                                                           |
| ----------------- | ---------------------------------------------------------------------- |
| `api_url`         | The URL of the Cycloid API                                             |
| `stack_author`    | The username of the user who creates the stack                         |
| `stack_canonical` | The stack canonical filled in by the user                              |
| `stack_path`      | The path of the generated stack in the catalog repository              |
| `stack_usecase`   | The key of the selected use case                                       |
| `scs_canonical`   | The canonical of the target catalog repository                         |
| `scs_cred_path`   | The path in Vault of the target catalog repository credential          |
| `scs_cred_type`   | The type of the target catalog repository credential (`ssh` or `http`) |

## Template engine reference[​](#template-engine-reference "Direct link to Template engine reference")

Blueprint uses golang text/template engine with [sprig functions](https://github.com/Masterminds/sprig).

The templating feature are the same as the kubernetes helm template language.

You can get the [list of template functions here](https://helm.sh/docs/chart_template_guide/function_list/).

Don't forget that for blueprints, the delimiter is `($>` `<$)` instead of `{{` `}}`.

### Cheat sheet[​](#cheat-sheet "Direct link to Cheat sheet")

* [functions](https://helm.sh/docs/chart_template_guide/function_list/)
* [control flow](https://helm.sh/docs/chart_template_guide/control_structures/)

Here is a quick cheat sheet of useful snippets to use:

#### Conditions[​](#conditions "Direct link to Conditions")

```
# and comparison
($> if and .Arg1 .Arg2 <$)
($> end <$)

# or comparison
($> if or .Arg1 .Arg2 <$)
($> end <$)

# not comparison
($> if not .Arg <$)
($> end <$)

# equal comparison
($> if eq .Arg1 .Arg2 <$)
($> end <$)

# not equal comparison
($> if ne .Arg1 .Arg2 <$)
($> end <$)

# less than comparison
($> if lt .Arg1 .Arg2 <$)
($> end <$)

# more than
($> if gt .Arg1 .Arg2 <$)
($> end <$)

# loops
($> with .ListItem <$)
  ($> .itemSubKey <$)
($> end <$)

# To ignore a template directibe line, add - to the first delimiter
($>- if and .Arg1 .Arg2 <$)
($>- end <$)
```


---

# Stackforms

In Cycloid, a project's configuration can be exposed to users within a text editor or within a user-generated interface using StackForms.

StackForms provides a graphical interface to offer much better control over projects' creation or update.

For a stack user, it provides a visual way to configure a stack, displaying all parameters with associated descriptions split into sections and groups. On top of that the variable can benefit from extra then definitions: required/optional, description, values range/input, default value, etc. By doing so it makes it easier for users to understand and provide the appropriate configuration.

StackForms is compatible with Cycloid components, as special widgets allow users to select their own Credentials, Config repositories, etc. And also work with TerraCost to display in live an estimated cost of an infrastructure based on selected parameters!

Once the configuration is saved/updated, it is directly written in your project's config repository.

![Stackforms-demo](/assets/images/stackforms-demo-0842f6e99942b6ff6ccf02aa12fc1c4f.gif)

## List of main benefits[​](#list-of-main-benefits "Direct link to List of main benefits")

Here is a list summarizing the main benefit of using such feature.

1. Nice visual interface
2. Support of a wide range of types and widgets
3. Improved control on which variables to expose
4. Capacity to make the variable require or not - and/or have default values
5. Enforce limitations of values (range, list of values)
6. Basic template capacities for variables (linked to organization, projects, etc)
7. Easier access to Cycloid's entities (credential, config repositories, etc)
8. Capacity to run a cost estimation of the project
9. Centralization of variables definition
10. Get dynamic values from the Inventory
11. ...and many more to come!


---

# Common use case

As described in the [file format](/reference/stackforms/concepts/forms-file.md) page, if you are working with a stack containing several use cases, each use case has to be defined in StackForms.

Some of the variables and groups could be common across several use cases. This is where StackForms' special use case called `cycloid-common` could be useful. The content of this use case will be automatically merged with all other defined use cases in StackForms.

This happens in various situations. Imagine a stack to deploy an application on several cloud providers, where each stack use case would define how to deploy the application on a specific cloud provider.

In such scenarios, you could have application-specific parameters that could be the same across all use cases, such as the version of the application to deploy, admin user, color theme, etc. This can be leveraged by defining them only once in the `cycloid-common` instead of doing so in every section. The only differences between use cases would be the parameters specific to the cloud provider.

If a section/group was defined in `cycloid-common` and not in the others, those would be added to them. However, if those were already defined, only the missing ones would be added, meaning any groups or variables defined in the other use cases have priority over the common one.

The process of merging elements is done prior to returning it to the user, so they will only see the final result.

The following examples will illustrate what the file looks like prior to the various injections of the `cycloid-common` use case into the other ones.

Example of a file defined with the **cycloid-common** use case:

raw .forms.yml

```
use_cases:
- name: cycloid-common
  sections:
  - name: Application config
    groups:
    - name: Global
      vars:
      - key: admin_user
        name: Admin username
      - key: app_version
        name: Version

- name: AWS
  sections:
  - name: Cloud config
    groups:
    - name: Access
      vars:
      - key: aws_access
        name: Cloud provider access keys

- name: GCP
  sections:
  - name: Cloud config
    groups:
    - name: Access
      vars:
      - key: gcp_access
        name: Cloud provider access keys
```

This file will virtually produce the following StackForms files for both AWS and GCP use cases:

* AWS
* Google Cloud Platform

.forms.yml

```
use_cases:
- name: AWS
  sections:
  # Section from cycloid-common
  - name: Application config
    groups:
    - name: Global
      vars:
      - key: admin_user
        name: Admin username
      - key: app_version
        name: Version

  - name: Cloud config
    groups:
    - name: Access
      vars:
      - key: aws_access
        name: Cloud provider access keys
```

.forms.yml

```
use_cases:
- name: GCP
  sections:
  # Section from cycloid-common
  - name: Application config
    groups:
    - name: Global
      vars:
      - key: admin_user
        name: Admin username
      - key: app_version
        name: Version

  - name: Cloud config
    groups:
    - name: Access
      vars:
      - key: gcp_access
        name: Cloud provider access keys
```


---

# Conditions

![Group-condition](/assets/images/condition-c56492638986d928a61ba0ce1db34c4b.gif)

The `condition` attribute can be applied to **groups** or **values** within your StackForms configuration. It enables dynamic behavior, allowing certain validations and enabling/disabling groups based on predefined criteria.

tip

Variables belonging to the group with a `condition` will only be processed if that group's `condition` is met; otherwise, variables will simply be ignored.

.forms.yml

```
use_cases:
- name: default
  sections:
  - name: section1
    groups:
    - name: group1
      technologies: [terraform]
      condition: ...
      vars:
      ...
```

You can employ complex logical expressions, although previously only a single expression was accepted.

Consider this simple use case: You're creating a stack for deploying a database, allowing users to choose between `Mysql` or `Psql` as the database engine. Depending on the user's choice, your forms could adapt and display only MySQL or PostgreSQL-related configuration options.

For example, the following condition is considered valid:

```
condition: $var1 == 'hello world' && $var2 > 10 || ($var3 != true && $var4 == 'value')
```

Here are few others condition examples:

```
# Compare a bool
condition: $var1 == true

# Compare a string
condition: $var1 == 'foo'

# Compare with a Cycloid special variable
condition: $var1 == '($ .env $)'
```

To better understand how to use conditions, refer to the subsections below for variable formats, available operators, and values.

## Examples[​](#examples "Direct link to Examples")

### Condition on group scope[​](#condition-on-group-scope "Direct link to Condition on group scope")

Using conditions at the group level is quite useful when you want to display or hide an entire group of user inputs.

For example, imagine you have optional components in a stack. Depending on whether these components are enabled or not, you would like to display the user input group to configure them.

* Code
* Rendering

.forms.yml

```
use_cases:
- name: "default"
  sections:
  - name: "My section"
    groups:
    - name: "My group1"
      technologies: ["pipeline"]
      vars:
        - name: "myvariable1"
          widget: switch
          key: myvariable
          type: "boolean"
          default: true

    - name: "My group2"
      condition: "$myvariable == true"
      technologies: ["pipeline"]
      vars:
        - name: "var2"
          widget: simple_text
          key: myvariable2
          type: "string"
```

![conditions](/assets/images/conditions-49c061170639dc415a9fbe44082a7f1c.gif)

### Condition on values scope[​](#condition-on-values-scope "Direct link to Condition on values scope")

Certain widgets in StackForms, like dropdowns, offer users a selection of values from a predefined list. To simplify the form and provide more flexibility, you can define a dynamic set of choices in the `values` and `default` attributes based on specific conditions. These values will adjust depending on the user's input.

For instance, consider a form where a user can select a database engine and also choose its version. Here's an example:

* Rendering
* Code

![](/assets/images/stackforms-dynamic-values-abe044ccc5b1bc06eb54eba374086296.gif)

.forms.yml

```
use_cases:
- name: "default"
  sections:
  - name: "Example section"
    groups:
      - name: "Relational Database"
        technologies: ["pipeline"]
        vars:
          - name: Database engine
            key: database_engine
            widget: dropdown
            values:
              - MySQL
              - PostgreSQL
            type: string
            required: true
            default: MySQL

          - name: Database engine version
            key: database_engine_version
            widget: dropdown
            type: string
            required: true
            values:
              options:
                - condition: $database_engine == 'MySQL'
                  values: ["8.0", "5.7"]
                - condition: $database_engine == 'PostgreSQL'
                  values: ["13", "14", "15"]
            default:
              options:
                - condition: $database_engine == 'MySQL'
                  default: "8.0"
                - condition: $database_engine == 'PostgreSQL'
                  default: "15"
```

In this example, the options for the `Engine Version` dropdown change dynamically based on the selected database engine (`MySQL` or `PostgreSQL`). This approach provides users with tailored choices based on their initial selection, enhancing the user experience and form flexibility.

#### Value mapping and dynamic values example[​](#value-mapping-and-dynamic-values-example "Direct link to Value mapping and dynamic values example")

Here is another complete example that combines dynamic values and the usage of mapped values. In this example, instance sizes from the cloud provider have been simplified by T-shirt size naming. The available sizes would vary depending on the environment used.

* Rendering
* Code

![](/assets/images/condition-dynamic-values-f505a18ec01c478daa820cc6e70381c0.gif)

.forms.yml

```
use_cases:
- name: "default"
  sections:
  - name: "My section"
    groups:
    - name: "My group"
      technologies: ["pipeline"]
      vars:
        - name: "Environment type"
          key: "env"
          widget: "dropdown"
          default: "dev"
          type: "string"
          values: ["dev", "prod"]

        - name: "Dynamic instance type selection"
          key: "instance_type"
          widget: "radios"
          type: "map"
          values:
            options:
              - name: "Dev instance types" # Optional a name to apply to this option
                condition: "$env == 'dev'"
                values:
                # highlight-next-start
                  - {"label": "S", "value": "t2.nano"}
                  - {"label": "M", "value": "t2.small"}
                  - {"label": "L", "value": "t2.medium"}
                # highlight-next-end
              - name: "Prod instance types"
                condition: "$env == 'prod'"
                values:
                  - {"label": "L", "value": "m5.large"}
                  - {"label": "XL", "value": "m5.xlarge"}
                  - {"label": "XXL", "value": "m5.2xlarge"}
          default:
            options:
              - name: "Dev default variable"
                condition: "$env == 'dev'"
                default: "S"
              - name: "Prod default variable"
                condition: "$env == 'prod'"
                default: "XL"
```

## Variables[​](#variables "Direct link to Variables")

The variables used in the condition expressions correspond to the StackForms variables specified by the `key` attribute and their corresponding values that will be verified in the condition.

Condition variables should be prefixed with the `$` symbol and cannot contain spaces or special characters, e.g., `$var1` or `$var_1` are valid variables.

Only the following variable types can be used in the expressions: `integer`, `float`, `string`, and `boolean`.

The supported value formats to use in the expressions are:

* `boolean`: `true` or `false`
* `integer` and `float`: `123.45`, `25`, and `-100` (to check negative numbers)
* `string`: `'text_string'`
* `dates`: `'2022-10-04_13:37:37Z'`. RFC3339, ISO8601, Ruby date, or Unix date formats are supported. All string/date values are required to be enclosed within single quotes. Date values can only be compared when using string variables.

info

Variables of type `map`, `array`, and `raw` are not supported yet.

## Operators[​](#operators "Direct link to Operators")

There's two operators to use in conditions:

* `Comparators` that are used to compare variables to values in a expression, as follows `$variable $comparator $value` Available comparators are:

  * `>` greater than
  * `>=` greater than or equal
  * `<` less than
  * `<=` less than or equal
  * `==` equal
  * `!=` not equal
  * `IN` Membership, eg `$foo IN (1, 2, 3, 4)`

* `Logical operators` that are used to establish logical value, as follows `$expressionA $logicalOperator $expressionB`. You can group expressions by using parentesis: `($expression) ...` Available logical operators:

  * `||` logical OR
  * `&&` logical AND

If you need more details, the engine used to evaluate operators is [Knetic/govaluate](https://github.com/Knetic/govaluate/blob/master/MANUAL.md)

## Specifications[​](#specifications "Direct link to Specifications")

### Rendering specificities[​](#rendering-specificities "Direct link to Rendering specificities")

As explained in the introduction, StackForms generates configuration files based on sample files. Everything defined in StackForms will be added or updated in the sample file during rendering. Everything else present in the sample files will remain unchanged.

When using conditions, variables that are ignored will be considered as not defined in StackForms. This means that if a variable is present in the sample file, StackForms will leave it in place.

This could be used as a workaround to hardcode specific default values directly in the sample file. This information could be useful depending on the technology you intend to use.

### Group variables scope[​](#group-variables-scope "Direct link to Group variables scope")

The `condition` at group level **cannot** use a variable contained inside of the current `group`. The below example **will fail**:

Example

This will **NOT** work, you can't use `foo` variables in condition here:

.forms.yml

```
use_cases:
- name: Default
  sections:
  - name: Section1
    groups:
    - name: "Bad group"
      technologies: [pipeline]
      condition: "$foo"
      vars:
      - name: "Enable the current group"
        key: "foo"
        widget: "switch"
        type: "boolean"
        default: true
      - name: "other var"
        key: "myvar"
        widget: text_area
        type: string
      - name: "toto"
        key: "toto"
        widget: text_area
        type: string
```


---

# Dynamic values

This section cover how to create forms filled with dynamic values using the `values_ref` attribute.

The `values_ref` should contain an URL pointing to a remote location that returns a JSON object. This JSON object is utilized as a source of data, providing dynamic content. This field replaces the `values` attribute.

By leveraging the `values_ref` field, users can dynamically populate fields, dropdowns, or other interactive components with data retrieved from the specified URL.

* Code
* Widget

```
      - name: "Amazon AWS region"
        description: "Amazon AWS region to use for Terraform."
        key: aws_region
        widget: auto_complete
        type: string
        values_ref: https://cycloid-demo-stackforms-values.s3.eu-west-1.amazonaws.com/aws-regions.json
        default: eu-west-3
        required: true
```

URL: <https://cycloid-demo-stackforms-values.s3.eu-west-1.amazonaws.com/aws-regions.json> ![forms-value-ref](/assets/images/forms-value-ref-ec1277aa30712bd6d4ab9380699908c8.png)

The content retrieved from the URL can be static or dynamically generated, as long as it adheres to the compatible JSON format. The format is the same as the `values` attribute. It accepts maps, arrays, as well as dynamic values and conditions using the same format as `values`. More information about dynamic values and conditions can be found in the dedicated concepts pages.

Here is a small example of URL content:

https\://cycloid-demo-stackforms-values.s3.eu-west-1.amazonaws.com/aws-regions.json

```
[
  "ap-south-1",
  "eu-north-1",
  "eu-west-3",
  "eu-west-2",
  "eu-west-1",
  "ap-northeast-3",
  "ap-northeast-2",
  "us-east-1",
  "us-east-2",
  "us-west-1",
  "us-west-2"
]
```

### Using Variables in `values_ref` URL[​](#using-variables-in-values_ref-url "Direct link to using-variables-in-values_ref-url")

To enhance dynamism based on user inputs, you can incorporate variables in `values_ref` URLs using the `${var}` format sourced from other StackForms variables.

For instance, if you have a forms file defining a `simple_text` variable named `foo`, you can utilize this variable to dynamically construct a URL for `values_ref`.

```
values_ref: https://myorganization.github.io/data/${foo}.json
# Or
values_ref: https://myorganization.github.io/api?selected=${foo}
```

* Rendering
* Code

![](/assets/images/stackforms_dynamic_value_ref-d0b87582418b49527d683624f3812247.gif)

.forms.yml

```
use_cases:
- name: default
  sections:
  - name: terraform
    groups:
    - name: application
      technologies: [pipeline]
      vars:
      - name: Team
        description: The team responsible for this environment
        key: team
        widget: dropdown
        type: string
        values:
          - frontend
          - backend
          - ops
      - name: User
        description: The user responsible for this environment
        key: user
        widget: auto_complete
        type: string
        values_ref: https://myorganization.github.io/data/users_${team}.json
        required: true
```

### Return Condition with `values_ref`[​](#return-condition-with-values_ref "Direct link to return-condition-with-values_ref")

In some advanced use cases, the `values_ref` format is not limited to returning only a list of values. It can also return conditions on values.

Here is a simple example of the possible format:

https\://url-example.com

```
{
   "options":[
      {
         "condition":"$test == 'foo'",
         "values":[
            "foo",
            "foo2"
         ]
      },
      {
         "condition":"$test == 'bar'",
         "values":[
            "bar",
            "bar2"
         ]
      }
   ]
}
```


---

# .forms file

The Stackform definition is contained in a file called `.forms.yml`, located at the same location as your [.cycloid.yml file](/reference/stacks/concepts/stack-concept.md).

The overall structure can be represented using the following definition:

```
use_cases:
- name: use-case-N
  sections:
  - name: section-A
    groups:
    - name: group-1
      vars:
        # variables definition here
```

The structure must adhere to the following:

* **use-case**: A list of use cases that must match the [.cycloid.yml file](/reference/stacks/concepts/stack-concept.md) use-case definition.
* **section**: A list of sections, these are logical grouping entities that allow for easier splitting of variables and understanding of the configuration.
* **group**: A list of groups, these serve two purposes - logical grouping entities and configuration that will apply to variables of the group (see explanation below).
* **variables-definition**: *Please see the next section for an extended description of the format.*

warning

As previously mentioned, the use-case should match the one from the [.cycloid.yml file](/reference/stacks/concepts/stack-concept.md). If a use-case present in the stack file isn't present in the `.forms.yml` you will get an error.

You can declare a use case with 0 sections to avoid this (if you don't want to use stackforms for some use cases.)

The sections and groups allow you to split your configuration into logical categories, and you are free to pick any name for those. For example, you could have a section dedicated to your `Application`, with groups specific for each service: `Cache settings`, `Versions to use`, `Database parameters`, etc.

However, a group's definition not only contains the list of variables but also the technologies for which this configuration applies. For more details, please see the [technologies](/reference/stackforms/concepts/technologies.md "Technologies description") section.

See the [next section on variables](/reference/stackforms/concepts/variables.md "Variable reference") for a more concrete example.

tip

To simplify the process of writing a StackForms file, we offer tools such as an [**online editor**](/reference/stackforms/reference/editor.md). This editor allows you to write and validate your StackForms file with ease.

## Field `use_cases`[​](#field-use_cases "Direct link to field-use_cases")

A use case in StackForms (and in a [Cycloid stacks](/reference/stacks/concepts/stack-concept.md)), represents a different 'scenario' for your stack.

For example, you can create one use-case for each cloud provider in a stack. Or maybe implement the same application deployment with different technologies.

Use cases allow you to state different ways to use your stack.

### Attributes[​](#attributes "Direct link to Attributes")

| Key      | Type                                | Description                                                                        |
| -------- | ----------------------------------- | ---------------------------------------------------------------------------------- |
| name     | string                              | The name of the current usecase (it should match the name defined in .cycloid.yml) |
| sections | list of [sections](#field-sections) | A list of sections                                                                 |

```
---
use_cases:
- name: "use_case_1"
  sections:
      [...]
```

## Field `sections`[​](#field-sections "Direct link to field-sections")

Sections are logical grouping entities that allow you to split your variables into different human-friendly categories.

For example, for a web application deployed on a cloud, you could define the following sections: Cloud access, Instance settings, Application settings, ...

A section can have multiple groups (requires at least 1).

### Attributes[​](#attributes-1 "Direct link to Attributes")

| Key    | Type                            | Description                     |
| ------ | ------------------------------- | ------------------------------- |
| name   | string                          | The name of the current section |
| groups | list of [groups](#field-groups) | A list of groups                |

```
---
use_cases:
- name: "use_case_1"
  sections:
  - name: "section_1"
    groups:
      [...]
```

## Field `groups`[​](#field-groups "Direct link to field-groups")

This is where you can define your StackForms variables.

Groups help to sort and group variables in a section and affect a technology to it. If we take back the example of an Instance settings section, we could create such groups: Size, Network, Backup, ...

In addition, Groups can have conditions used to enable the group depending on another variable. For more information about conditions, see the [condition section](/reference/stackforms/concepts/conditions.md "Conditions reference").

### Attributes[​](#attributes-2 "Direct link to Attributes")

| Key            | Type                                                                                              | Description                                                                                                                                         |
| -------------- | ------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`         | string                                                                                            | The name of the group                                                                                                                               |
| `vars`         | list of [variables](/reference/stackforms/concepts/variables.md "Variable reference")             | The list of variable definitions.                                                                                                                   |
| `technologies` | list of [technologies](/reference/stackforms/concepts/technologies.md "Technologies description") | Samples file technologies where to write variables. Default use group technologies, values `pipeline`, `terraform` or `ansible`                     |
| `condition`    | string                                                                                            | A conditional expression to enable/disable the current group. see [conditions](/reference/stackforms/concepts/conditions.md "Conditions reference") |

```
---
use_cases:
- name: "use_case_1"
  sections:
  - name: "section_1"
    groups:
    - name: "group1"
      technologies:
      - "terraform"
      - "ansible"
      vars: []
      [...]
```

## Example[​](#example "Direct link to Example")

This example will represent a project that uses use-cases for managing different cloud providers.

Here we make a configuration for using the same stack for deploying to GCP or AWS.

* Result
* Stack config
* StackForms config

![Screenshot of the redered StackForms, section AWS](/assets/images/use_case_example_1-fe9abf423c17b6c7b93f9a21dec312d9.png) ![Screenshot of the redered StackForms, section GCP](/assets/images/use_case_example_2-f79b2f459af66456eb17ac7f149af6d3.png)

.cycloid.yml

```
---
name: "Cycloid project example"
canonical: "cycloid-project-example"
description: |
  This is a description

author: "John Doe"
image: "url-to-image"

config:
  aws:
    name: "AWS"
    description: "Deploy the app on AWS"

    pipeline:
      pipeline:
        path: "pipeline/pipeline.yml"
      variables:
        path: "pipeline/variables.sample.yml"
        destination: "($ .config_root $)/pipeline/variables.yaml"
    terraform:
      config:
        path: "terraform/aws/main.tf.sample"
        destination: "($ .config_root $)/terraform/main.tf"

  gcp:
    name: "GCP"
    description: "Deploy the app on GCP"

    pipeline:
      pipeline:
        path: "pipeline/pipeline.yml"
      variables:
        path: "pipeline/variables.sample.yml"
        destination: "($ .config_root $)/pipeline/variables.yaml"
    terraform:
      config:
        path: "terraform/gcp/main.tf.sample"
        destination: "($ .config_root $)/terraform/main.tf"
  # [...]
```

.forms.yml

```
---

use_cases:
- name: "aws"
  sections:
  - name: "Cloud provider settings"
    groups:
    - name: "Credentials"
      technologies: ["pipeline"]
      vars:
      - name: "AWS Region"
        key: "aws_default_region"
        type: "string"
        widget: "auto_complete"
        values:
          - "eu-west-3"
          - "eu-west-2"
          - "eu-west-1"
        default: "eu-west-1"
      - name: "AWS access keys"
        description: "AWS access key which should be used"
        key: "aws_cred"
        type: "string"
        widget: "cy_cred"
        widget_config:
          display_keys: false
          cred_types: ["aws"]
        default: "((aws))"

- name: "gcp"
  sections:
  - name: "Cloud provider settings"
    groups:
    - name: "Credentials"
      technologies: ["pipeline"]
      vars:
      - name: "GCP project name"
        description: "The GCP project name to use"
        key: "gcp_project"
        widget: "simple_text"
        type: "string"
        default: "cycloid-demo"
      - name: "GCP zone"
        key: "gcp_zone"
        widget: "auto_complete"
        type: "string"
        values:
          - "europe-west1-b"
          - "europe-west1-c"
          - "europe-west1-d"
        default: "europe-west1-b"
      - name: "GCP json credentials"
        description: "GCP credentials in json format which should be used"
        key: "gcp_credentials_json"
        widget: "cy_cred"
        type: string
        default: "((gcp_step-by-step.json_key))"
```


---

# Technologies

As described, StackForms creates a link between Infrastructure as Code (IaC) variables and HTML forms.

In a stack definition, you can specify one or several sample files that StackForms can utilize. These samples must be defined in the [.cycloid.yaml](/reference/stacks/reference/cycloid-file.md) file. Each sample file is part of the `config` section and is categorized by technologies. These technologies are accessible to StackForms.

StackForms natively supports two main languages: **YAML** and **HCL**. To provide additional features on top of these languages, they are split across several supported technologies according to the `.cycloid.yaml` file:

* **YAML**: `ansible` and `pipeline`
* **HCL**: `terraform`

A **technology** in StackForms represents a specific sample file target where user inputs are written. Depending on the selected technology, the Cycloid engine will adapt how a variable is rendered and written.

note

When a user input is a Cycloid **credential**, we recommend using the `pipeline` technology. Credentials are natively embedded in the pipeline engine, so it's usually easier to forward a variable from the pipeline to the specific technology rather than trying to use the credential engine inside the code. Refer to the section dedicated to forwarding [pipeline variables to technologies](/reference/ci-cd-pipelines/concepts/tools-integration/.md).

Each technology has specificities on how StackForms render and use variables.

## Pipeline[​](#pipeline "Direct link to Pipeline")

The Pipeline technology offers the simplest method to use StackForms variables, as they integrate in a similar manner to [Concourse variables](https://concourse-ci.org/vars.html) and [credentials](https://concourse-ci.org/creds.html).

Using the Pipeline technology, your variables are injected using the `variable.sample.yml` file. These variables are injected as [YAML](https://yaml.org/ "YAML documentation website").

### Standard[​](#standard "Direct link to Standard")

When using pipelines, as depicted in the schema below, StackForms writes user inputs as variables in the stack sample file (usually called *variables.sample.yaml*).

![stackforms-overview-details-pipeline](/assets/images/stackforms-overview-details-pipeline-bb2c9ad1529ce058f0edc3d8065c2446.png)

Subsequently, the generated variable file and pipeline template (usually called *pipeline.yaml*) are both sent to our API to create the final pipeline.

That being said, here is a small example to define a pipeline variable in StackForms and use it in a pipeline:

* Config example
* Rendering example

.forms.yml

```
use_cases:
- name: "demo"
  sections:
  - name: "Application"
    groups:
    - name: "source code"
      technologies: ["pipeline"]
      vars:
        - name: "Git url"
          key: "git_url"
          type: "string"
          widget: simple_text
```

![forms-pipeline-var](data:image/png;base64,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)

And use your variable in the pipeline:

pipeline/pipeline.yml

```
resources:
- name: source-code
  type: git
  source:
    uri: ((git_url))
    branch: master
```

You can use StackForms variables anywhere in your pipeline like regular Concourse variables.

## Terraform[​](#terraform "Direct link to Terraform")

To use [Terraform](https://developer.hashicorp.com/terraform) with StackForms, you must to structure your code as Terraform modules and provide a sample file that demonstrates how to use your module.

The module call must be inside the Terraform sample file defined in the `.cycloid.yaml` file, for example, `main.tf.sample`, which StackForms will parse and render as your `main.tf`.

Using the Terraform technology will inject user inputs as [module arguments](https://developer.hashicorp.com/terraform/language/modules "Terraform documentation: module arguments").

![stackforms-overview-details-sample](/assets/images/stackforms-overview-details-sample-58e92120b99ca0f95293884d3a65ea0b.png)

Stackforms will do the mapping between HTML forms and the provided samples files in order to write user input as variables in the appropriated format.

warning

There are some limitations in the Terraform module parsing.

important

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

* Currently, you can only use `modules` within Terraform sample files. If you use other types of elements (`depends_on`, `provider`, `resources`, etc.), these will be discarded or trigger an error, except if you set them in another dedicated sample file.
* Support is limited to only one level of Terraform modules; inner modules are not advised by Terraform and are not supported by StackForms.
* StackForms works only with Terraform syntax versions `>= 0.12.8`.

### Standard[​](#standard-1 "Direct link to Standard")

Given the example `simple_vm` module below:

simple\_vm/main.tf

```
// Module arguments
variable "disk_size" {
    type = number
    default = 10
}

variable "vm_os" {
    type = string
    default = "debian"
}

// Rest of code
// ...
```

According to this module definition, the sample file should look like this:

main.tf.sample

```
module "simple_vm" {
    source = "./simple_vm"

    // StackForms will inject `vm_disk_size` and `vm_os` variables directly here
    // Like this:
    // disk_size = "<value_in_stackforms>"
    // vm_os = "<value_in_stackforms>"
}
```

Here is a rough example of StackForms configuration to inject user input into the sample file:

* Config example
* Rendering example

.forms.yml

```
use_cases:
- name: "Using simple_vm"
  sections:
  - name: "Deploy"
    groups:
    - name: "Terraform variables"
      # Here we use the terraform technology
      technologies: ["terraform"]
      vars:
        - name: "OS"
          key: "vm_os"
          type: "string"
          default: "nixos"
          ...
        - name: "VM Disk size"
          key: "disk_size"
          type: "integer"
          default: 129
          ...
```

![Stackforms module example rendering part 1](/assets/images/technology_terraform_modules_example_1-75b5b260fb8c15a1a59b8a6abe806ffb.png)

StackForms relies on the `key` field to determine the name of the Terraform module argument to define. Using the configuration above would generate the following file in the config repository:

main.tf

```
module "simple_vm" {
    source "./simple_vm/"

    disk_size = 5
    vm_os = "debian"
}
```

info

Be careful to match the variables in StackForms and in your module arguments!

### Using multiple modules[​](#using-multiple-modules "Direct link to Using multiple modules")

By default, a variable with just a normal `key` as described above will be injected into *all module calls*.

Using the same example above, let's add a `simple_database` Terraform module call in the `main.tf.sample`:

Then add a call to the new `simple_database` in the `main.tf.sample`:

main.tf.sample

```
module "simple_vm" {
    source "./simple_vm/"
}

module "simple_database" {
    source "./simple_database/"
}
```

In this example, you could assume some user inputs would be used by the `simple_vm` module and some by `simple_database`. Potentially, some inputs could also be used in both.

This use case is supported in the Terraform technology. You can prefix the `key` attribute with your `module_name.` to make it available only to the specified Terraform `module`.

You could still use non-prefixed `key` attributes to add *global* variables to all your modules.

Let's add a `vpc_subnet` common variable, for example (this assumes that we add the `vpc_subnet` variable in both modules).

* StackForms Code
* Form rendering
* Terraform modules templated

.forms.yml

```
use_cases:
- name: "Using simple_vm"
  sections:
  - name: "Deploy"
    groups:
    - name: "Terraform variables"
      technologies: ["terraform"]
      vars:
        - name: "VPC Subnet"
          key: vpc_subnet
          type: string
          ...
        - name: "VM OS"
          key: "module.simple_vm.vm_os"
          type: "string"
          default: "debian"
          ...
        - name: "VM Disk size"
          key: "module.simple_vm.disk_size"
          type: "integer"
          default: 10
          ...
        - name: "Database disk size"
          key: "module.simple_database.disk_size"
          type: "integer"
          default: 10
          ...
        - name: "Database engine"
          key: "module.simple_database.engine"
          type: "string"
          default: "postgres"
          ...
```

![Stackforms module example rendering part 3](/assets/images/technology_terraform_modules_example_3-e05e860597fd3f14aa6305e035f44f34.png)

main.tf

```
module "simple_vm" {
    source "./simple_vm/"

    vpc_subnet = "<value>"
    disk_size = 10
    vm_os = debian
}

module "simple_database" {
    source "./simple_database/"

    vpc_subnet = "<value>"
    disk_size = 5
    engine = postgres
}
```

note

**Good Practice**: We recommend using the `module.var_name` variable key by default to avoid collisions between modules when extending your `main.tf.sample`.

## Ansible[​](#ansible "Direct link to Ansible")

The Ansible technology is quite similar to the Pipeline technology, with only slight differences when using Cycloid Credentials. More details will be provided in the dedicated section of the Cycloid credentials widget.

Integrating Ansible into Cycloid pipelines is made easier by a script provided in the [cycloid/cycloid-toolkit](/reference/ci-cd-pipelines/concepts/cycloid-toolkit.md) called *ansible-runner*.

**Ansible runner** is a wrapper for the [ansible-playbook](https://docs.ansible.com/ansible/latest/playbook_guide/playbooks_intro.html) command, which can be configured with several environment variables to simplify Ansible's integration into a pipeline and provide additional functions.

Depending on your usage, some user inputs would be better to be written directly in an Ansible variable file, while others can be passed to Ansible through the pipeline.

A complete example of usage in a Cycloid pipeline can be found in the [pipeline examples section](/reference/ci-cd-pipelines/concepts/tools-integration/ansible.md).

### Regular Ansible Sample File[​](#regular-ansible-sample-file "Direct link to Regular Ansible Sample File")

Similar to Terraform, Stackforms will map HTML forms to the provided sample files to write user input as variables in the appropriate format.

![stackforms-overview-details-sample](/assets/images/stackforms-overview-details-sample-58e92120b99ca0f95293884d3a65ea0b.png)

For Ansible, we implement this concept of stacks and sample files using `vars_files` and an empty YAML file as a sample, called `empty.yml`.

In our stack, we create the following files:

```
├── ansible
│   └── playbook.yml             # Our actual Ansible playbook
│   └── environments/
│      └── default_front.yml     # Our default Ansible variables
│      └── empty.yml             # An empty YAML file, used in the code, but also as a sample file in the Cycloid stack
```

Then in the playbook file, we write the following lines:

```
vars_files:
  - "environments/default_front.yml"
  - [ "environments/{{ env }}-user-inputs.yml", "environments/empty.yml" ]
```

This way, during Ansible run, all default variables are loaded from `default_front.yml`. Then, the file generated by Stackforms, `{{ env }}-user-inputs.yml`, overrides Ansible variables with user inputs.

## Custom Technology[​](#custom-technology "Direct link to Custom Technology")

You're likely already familiar with [templating stack configuration](/reference/stacks/concepts/templating.md). Templating files with Custom Technology is the same concept applied to your template files, enhanced with stack form values.

This technology lets you define a set of templates to generate any type of files that can be populated with stack form values and project-specific settings.

Unlike some other methods, this technology does not require a pipeline.

The templating engine is the same as the [Cycloid stack templating](/reference/stacks/concepts/templating.md) with added StackForms variables.

Useful related links

* [.cycloid file reference](/reference/stacks/reference/cycloid-file.md).
* [Cycloid templating](/reference/stacks/concepts/templating.md)

To use the Custom Technology, you need to define templates and a destination in the `.cycloid.yml` file.

.cycloid.yml

```
...
config:
  some_use_case:
    custom:
      # Custom Technology needs to write the stackforms variables in a file
      # set the path to this file here.
      var_path: ($ .config_root $)/cy_vars/file.json

      # Define the templates and their definitions
      # You can define as much as you need
      templates:
      # list of templates path, files or folder to evaluate
      - paths:
        - some_folder/main.yaml.tmpl
        # list of helper path to add for each template evaluation
        helpers:
        - parts/
        - common.tmpl
        # destination path in config repository, will be a folder by default
        destination: ($ .config_root $)/dest-folder

        # You can template multiple file to a target file like this.
        # In this case, all the source file will be concatenated to the
        # destination
      - paths:
        - source_templates/
        destination: ($ .config_root $)/dest_file.yml
        # configuration of the templating
        config:
          destination_is_file: true
```

The default templating behavior is simple, each file/folder listed in a template declaration will be rendered in alphanumeric order and recursively.

So for a template declaration like this:

```
./templates/
./templates/a.yaml.tmpl
./templates/b.yaml.tmpl
./templates/sub_folder/c.yaml.tmpl
```

With this configuration in the `.cycloid.yml` file

.cycloid.yml

```
... # Top of the file omitted
config:
  some_use_case:
    custom:
      var_path: ($ .config_root $)/cy_vars/vars.json
      templates:
      - paths:
        - templates/
        destination: ($ .config_root $)/output
```

The generated files in the config repository will be:

Output in config repository

```
./<org>/<project>/<env>/<component>/cy_vars/vars.json
./<org>/<project>/<env>/<component>/output/a.yaml
./<org>/<project>/<env>/<component>/output/b.yaml
./<org>/<project>/<env>/<component>/output/sub_folder/c.yaml
```

note

The templating engine will strip the `.tmpl` suffix of the files names when processing them.

The suffix is not mandatory to template a file, the source name can be arbitrary.

Adding the `.tmpl` can help with syntax highlighting in some IDEs

#### Single file[​](#single-file "Direct link to Single file")

You can render templates in a single files. In that case, all files will be concatenated into one destination file in alphanumerical order.

This is useful for example to group kubernetes manifests into one file:

With this configuration in the `.cycloid.yml` file

.cycloid.yml

```
... # Top of the file omitted
config:
  kubernetes_use_case:
    name: "Some k8s Usecase"
    description: "Group manifests in one file."
    custom:
      var_path: ($ .config_root $)/cy_vars/vars.json
      templates:
      - paths:
        - templates/deployment.yaml.tmpl
        - templates/service.yaml.tmpl
        - templates/ingress.yaml.tmpl
        destination: ($ .config_root $)/manifests.yaml
        # You will need to specify the `destination_is_file: true` parameter in
        # the configuration.
        config:
          # Define that the destination path is a file
          destination_is_file: true
```

The generated files in the config repository will be:

Output in config repository

```
./<org>/<project>/<env>/<component>/cy_vars/vars.json
./<org>/<project>/<env>/<component>/manifests.yaml
```

warning

Don't forget the `destination_is_file` parameter or the output will be a folder named `manifests.yaml`:

Output in config repository

```
./<org>/<project>/<env>/<component>/cy_vars/vars.json
./<org>/<project>/<env>/<component>/manifests.yaml/deployment.yaml
./<org>/<project>/<env>/<component>/manifests.yaml/service.yaml
./<org>/<project>/<env>/<component>/manifests.yaml/ingress.yaml
```

### StackForms variables[​](#stackforms-variables "Direct link to StackForms variables")

The templating engine will have access to all variables declared in the `.forms.yml`.

You can access the variable using its `key` like so :

```
($ .key $)
```

In some case, variable names can contain `.`, notably the variables scoped to a module shared with the [terraform technology](/reference/stackforms/concepts/technologies.md#using-multiple-modules)

The variables using dots will be appended to a map. So if you declare two variables like that:

```
...
key: module.foo.hello
...
key: module.foo.world
...
key: module.bar.hello
```

You will get this data:

```
module:
  foo:
    hello: <value>
    world: <value>
  bar:
    hello: <value>
```

You can access them like so in the templating directive:

```
($ .module.foo.hello $)
($ .module.foo.world $)
($ .module.bar.hello $)
```

warning

Be careful, there is one edge case to this.

If you declare a variable like: `foo.bar`

And you add a variable named `foo` with `type: map`, you may erase the content of `foo.bar`.

Be careful on variable naming that could collide.

### Helpers[​](#helpers "Direct link to Helpers")

Helpers allow to define parts that can be re-used in templates.

Those files are sourced in the templating engine and will not be created on the destination.

To use them, define their path in the stack using the `.cycloid.yml`:

```
... # Top of the file omitted
config:
  some_use_case:
    name: "Some usecase"
    custom:
      var_path: ($ .config_root $)/cy_vars/vars.json
      templates:
      - helpers:
        - common/ # source all helpers files there
        - helper.tmpl # source a specific file
        paths:
        - templates/deployment.yaml.tmpl
        - templates/service.yaml.tmpl
        - templates/ingress.yaml.tmpl
        destination: ($ .config_root $)/manifests/
```

All the helpers define will be sourced and use in each template file evaluation.

To define a template labels use the syntax:

```
($- define "labels" $)
  labels:
    app: ($ default "nginx" .nginx.app_name $)
    features: ($ .features $)
    environment: ($ .environment $)
($- end $)
```

which can be used in a template as:

```
($- template "labels" . $)
```

### Destination type[​](#destination-type "Direct link to Destination type")

#### Directory[​](#directory "Direct link to Directory")

Default destination. In this case all template files found in the paths should be recreated in the destination directory, preserving the file structure (skipping the input folder name).

E.g.

```
paths:
- folder1/
- file0.txt
destination: /dest
```

with folder1 structure:

```
folder1/
├── file1.txt
└── folder2/
    └── file2.txt
```

will produce

```
dest/
├── file0.txt
├── file1.txt
└── folder2/
    └── file2.txt
```

#### File[​](#file "Direct link to File")

Configured with `destination_is_file: true`.

In this configuration all input templates are evaluated with their helpers, concatenated and then save in the destination path.

Using the example above, if `/dest` is a file, the output is a single file `/dest` that consists of `file0.txt` + `file1.txt` + `file2.txt`.

### Examples[​](#examples "Direct link to Examples")

The following example shows the more advance usage of the Custom Technology, defining the `destination_is_file` flag and the helpers.

* .cycloid
* .form
* source\_templates/main.tmpl

.cycloid

```
---
version: '4'
name: 'Custom Technology Showcase'
canonical: 'stack-templating'
description: 'This stack contains a bunch of template files that will be populated with values defined in the stack form.'
keywords:
  - 'templating'
  - 'custom'
author: 'Cycloid'
image: 'https://raw.githubusercontent.com/cycloid-community-catalog/stack-lemp/master/icon.png'
template: false
config:
  default:
    # Custom Technology can be defined separately or together with other technologies
    custom:
      var_path: ($ .config_root $)/cy_vars/file.json
      templates:
      - paths:
        - source_templates/main.tmpl
        - common/
        destination: ($ .config_root $)/dest_file.yml
        - helpers:
          - parts/
          - common.tmpl
        config:
          destination_is_file: true
      - paths:
        - source_templates/
        - common/
        destination: ($ .config_root $)/dest-folder/
```

.forms.yml

```
---
use_cases:
- name: "default"
  sections:
  - name: "Template variables"
    groups:
    - name: "User messages"
      technologies: ["custom"]
      vars:
      - name: "User message"
        key: "user_message"
        widget: "simple_text"
        type: "string"
        default: "Hello world!"
```

```
This is an example template content:

The stack version is ($ .version $) and the use case is ($ .use_case $).
These two variables are Cycloid Special Variables, populated automatically.

The user defined variables get their values via a stack form.
The user says:

($ .user_message $)
```

When a component is instantiated from this stack, the corresponding template file will be generated in the configuration repository linked to this project, at `$(.config_root)/dest_file.yml`.

The resulting file will contain the following:

```
This is an example template content:

The stack version is 4 and the use case is default.
These two variables are Cycloid Special Variables, populated automatically.

The user defined variables get their values via a stack form.
The user says:
Hello world!
```

## Advanced usage[​](#advanced-usage "Direct link to Advanced usage")

<!-- -->

### Utilize the Same Variable Across Technologies[​](#utilize-the-same-variable-across-technologies "Direct link to Utilize the Same Variable Across Technologies")

You can also share variables across different technologies. Simply add the relevant technologies to the list within the group, and the variables will automatically be read from and written to their respective files.

.forms.yml

```
use_cases:
- name: "demo"
  sections:
  - name: "Deploy"
    groups:
    - name: "Common"
      technologies: ["pieline","terraform"]
      vars:
      ...
```

This feature can be quite beneficial, especially when you want to avoid duplicating identical variable definitions for different technologies.

*However, if these shared variables are no longer identical (for instance, if they are manually edited), users will be notified and will need to resolve the conflict manually.*

warning

Please note that only a subset of widgets supports sharing at this time. Refer to the table below for details:

| Widgets                                                                                                              | Can be shared? |
| -------------------------------------------------------------------------------------------------------------------- | -------------- |
| `auto_complete`, `dropdown`, `number`, `radios`, `simple_text`, `slider_list`, `slider_range`, `switch`, `text_area` | ✅             |
| `cy_cred`, `cy_scs`, `cy_crs`, `cy_branch`                                                                           | ❌             |


---

# Map value mapping

Sometimes, when using a form, you may prefer to display text instead of specific values, especially if the values are not very clear to users. For instance, you might want to simplify cloud provider instance types by displaying `L` instead of `m5.large`.

To accomplish this, you can use the `map` type, where values and defaults are formatted differently. They should include `label` (the displayed text) and `value` (the associated value) fields.

For example, let's say you want users to select from various instance flavors. You can achieve this as follows:

* Code
* Rendering

.forms.yml

```
use_cases:
- name: prod
  sections:
  - name: ansible
    groups:
    - name: database
      technologies:
      - ansible
      vars:
      - name: Mapped variable
        description: S is t2.small, M is t2.medium, L is t2.large
        widget: slider_list
        type: map
        key: mapped
        values:
        - {label: S, value: t2.small}
        - {label: M, value: t2.medium}
        - {label: L, value: t2.large}
        default: L
```

![forms-mapped](/assets/images/forms-mapped-17e3bdfe97d51c1b01de5e41ba8a86c8.png)

This approach ensures that users see simpler and more understandable names instead of potentially confusing technical terms when making selections.

warning

Be careful, using value mapping with conditions refer to the label and not the value, see the [value mapping and dynamic value example](/reference/stackforms/concepts/conditions.md#value-mapping-and-dynamic-values-example).


---

# Validation

This attribute provides comprehensive validation options, including regular expression (RegExp) patterns for the `simple_text` widget, and specific key and element validations for the `text_area` widget. These validations ensure that user inputs adhere to specific rules, which can be tailored to unique use cases such as IP addresses, phone numbers, alphanumeric strings, and more.

Additionally, there's a requirement to ensure a minimum number of entries in an array or the presence of a key in the map. This will help you enforce specific conditions in forms submissions.

Compatibility

Regexp Validation is currently limited to `simple_text` widget.

## Understanding Regexp Validation[​](#understanding-regexp-validation "Direct link to Understanding Regexp Validation")

Regular expressions (regex or regexp) are used to match patterns within text. By leveraging regex, you can specify particular patterns that data must adhere to, providing a high degree of control and flexibility for data validation.

Our engine mostly support all expression format from [JavaScript expressions](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_expressions).

## How It Works[​](#how-it-works "Direct link to How It Works")

With Stackforms, implementing regexp validation for your `simple_text` widgets is straightforward. You can define custom regexp patterns in your `.forms.yml` file for each field.

If the entered data doesn't match a specified regular expression, Stackforms will display a predefined error message.

## RegExp validation example[​](#regexp-validation-example "Direct link to RegExp validation example")

.forms.yml

```
  - name: "variable with validation"
    description: "this is a string"
    key: "key-one"
    widget: simple_text
    type: string
    required: true
    validations:
      - regexp: '.*test.*'
        error_message: 'the value must contain the word test'
      - regexp: '.*example.*'
        error_message: 'the value must contain the word example'
      - regexp: '^[a-z0-9- ]+$'
        error_message: 'The value must be only lowercase char, integer, spaces or "-"'
```

Under the validations section, you have defined two regexp validations for this string field.

**Validation Details**:

* `regexp`: The regular expression pattern to be applied to the field's value, `'.*test.*'.` and on the second validation: `'.*example.*'.`. This pattern checks if the value contains the word `test` and the second one check the word `example`. The last pattern `'^[a-z0-9- ]+$'` ensure the user input contains only specific chars, integer, ... be careful, the usage of `^ and $` is really important in order to apply the regex on the entier text. That means a sentence like `this is a good test example` will match the criterias.

* `error_message`: The error message associated with this validation. If the validation fails (i.e., the word "test" and "example" are not present in the field's value), the error message 'the value must contain the word test/example' will be displayed.

In the validations array, you can include multiple regular expressions. When you define more than one validation, it's important to understand that all of these validations must be met for the field to pass validation. Think of it as an **AND** operator from a logical perspective – all conditions need to be satisfied for the field to be considered valid.

With this YAML configuration, you've added specific regexp validations to ensure that the field value adheres to the specified patterns, and you've provided clear error messages to inform users when their input does not meet these criteria.

Compatibility

Array and map validations are currently limited to the `text_area` widget.

## Understanding Array and Map Validation[​](#understanding-array-and-map-validation "Direct link to Understanding Array and Map Validation")

Array and map validations are essential for ensuring the integrity and correctness of your data. These validations include requiring a minimum number of entries, a maximum number of entries, and the presence of specific elements in an array, as well as ensuring specific keys are present in a map.

## How It Works[​](#how-it-works-1 "Direct link to How It Works")

Setting up array and map validations for your `text_area` widgets is simple. You can specify custom validation rules directly in your `.forms.yml` file for each field. When the entered data doesn't meet the defined criteria, StackForms will show a predefined error message.

## Array validation example[​](#array-validation-example "Direct link to Array validation example")

.forms.yml

```
use_cases:
- name: default
  sections:
  - name: Application
    groups:
    - name: File upload
      technologies: [pipeline]
      vars:
        - name: "Image MIME types"
          key: image-mime-types
          widget: text_area
          type: array
          default:
            - "image/jpeg"
            - "image/png"
            - "image/gif"
            - "image/webp"
          validations:
            - array:
                min_elems: 2
              error_message: "At least two image types must be defined"
            - array:
                max_elems: 6
              error_message: "No more than six image types can be defined"
            - array:
                must_exist_elems: ["image/jpeg"]
              error_message: "image/jpeg MIME type must be present"
```

**Validation Details**:

* `min_elems`: Specifies the minimum number of elements that the array must contain. In this example, at least 2 elements are required.

* `max_elems`: Specifies the maximum number of elements that the array can contain. Here, it allows no more than 6 elements.

* `must_exist_elems`: Defines particular elements that must be present in the array. In this case, the array must include `["image/jpeg"]`.

* `error_message`: The message displayed if the validation fails. If `error_message` is not provided, a default error message will be shown.

## Map validation example[​](#map-validation-example "Direct link to Map validation example")

.forms.yml

```
use_cases:
- name: default
  sections:
  - name: Application
    groups:
    - name: File upload
      technologies: [pipeline]
      vars:
        - name: "Load test parameters"
          key: load-test-params
          widget: text_area
          type: map
          default:
            users: 100
            duration: 10m
            endpoint: "/api"
          validations:
            - map:
                must_exist_keys: ["endpoint"]
              error_message: "The endpoint key must be present"
```

**Validation Details**:

* `must_exist_keys`: Defines specific keys that must be present in the map. In this example, the key "endpoint" must exist in the map.

* `error_message`: The message that will be displayed if the validation fails. If `error_message` is not provided, a default error message will be shown.


---

# Variables

In Stackforms, a variable defines the mapping between a specific variable in an Infrastructure as Code [technology](/reference/stackforms/concepts/technologies.md) (e.g., Pipeline, Ansible, Terraform, etc.) and an HTML widget displayed to a user.

A variable definition contains information about the IaC variable to write, such as the name, the type, the default value, and how to present it to the end user.

Below is the list of all attributes you could use to define a variable:

<!-- -->

| Attribute          | Type      |  Required | Description                                                                                                                                                                                                                                           |
| ------------------ | --------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **name**           | *string*  | yes       | name of the attribute displayed to the user                                                                                                                                                                                                           |
| **key**            | *string*  | yes       | key is the name of the IaC variable to write in the sample files from [.cycloid.yml file](/reference/stacks/reference/cycloid-file.md). See notes about key attribute                                                                                 |
| **type**           | *string*  | yes       | [the type](/reference/stackforms/concepts/variables.md#type) of data handled                                                                                                                                                                          |
| **widget**         | *string*  | yes       | [the widget](/reference/stackforms/concepts/widgets.md#available-widgets) used to display the data in the most suitable way                                                                                                                           |
| **description**    | *string*  | no        | description helping users understand the interest/impact of such variable/change. This supports [markdown format](https://www.markdownguide.org/basic-syntax/), so you can easily insert bold, italic or links into the description of your varaible. |
| **technologies**   | *array*   | no        | Samples file technologies where to write variables. Default use group technologies, values `pipeline`, `terraform` or `ansible`                                                                                                                       |
| **required**       | *boolean* | no        | whether or not the attribute is required                                                                                                                                                                                                              |
| **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                                                                                                                         |
| **default**        | *any*     | no        | the default value to assign to the attribute if nothing is set by the user. Must be of the correct [type](/reference/stackforms/concepts/variables.md#type)                                                                                           |
| **values**         | *any*     | no        | list of allowed values, this attribute depend of the [widget](/reference/stackforms/concepts/widgets.md#available-widgets) selected                                                                                                                   |
| **values\_ref**    | *string*  | no        | Provide [dynamic values](/reference/stackforms/concepts/dynamic-values.md) using and URL to a remote location that will return a JSON that will be used as `values`, can be used anywhere `values` is used                                            |
| **validations**    | *array*   | no        | Define custom regexp patterns to validate user inputs, see [value validations page](/reference/stackforms/concepts/value-validations.md)                                                                                                              |
| **widget\_config** | *map*     | no        | Widget-specific configuration. Content based on the widget used. Please refer to the widget reference documentation for detailed information on how to configure each widget accordingly.                                                             |

The strict minimum definition of a variable could looks like:

.forms.yml

```
---
use_cases:
- name: myusecase
  sections:
  - name: mysection
    groups:
    - name: mygroup
      technologies: [pipeline]
      vars:
        - name: "Pipeline variable"
          key: my_pipeline_variable
          widget: simple_text
          type: string
```

The most important attributes are:

* `key`: This attribute represents the actual variable name in the selected Infrastructure as Code technology.
* `type`: This attribute defines the type of user input, such as integer, string, etc.
* `widget`: This attribute specifies the HTML widget used to visually represent the variable to the user.

## Attributes[​](#attributes "Direct link to Attributes")

### `key`[​](#key "Direct link to key")

The `key` attribute should be unique within a form. As explained before, it is used to map an Infrastructure as Code variable name to a Stackforms variable/widget.

This attribute may have specific requirements depending on the [technologies](/reference/stackforms/concepts/technologies.md) used.

### `type`[​](#type "Direct link to type")

Type constraints ensure that the provided data matches the expected type. If a string is passed instead of a number, an error will be triggered. The same applies if defaults or values are set that do not adhere to the type.

Constraints on types may vary depending on the widget used.

The list of supported types includes:

* **`integer`**: An integer number.
* **`float`**: A floating-point number.
* **`string`**: Any type of string.
* **`array`**: Any type of array (number, string, etc.).
* **`boolean`**: True or false.
* **`map`**: Any type of map.
* **`raw`**: Any content that is valid YAML/HCL depending on the technology.

The `map` type can be displayed as JSON but is properly converted to/from YAML/HCL when stored and retrieved.

The `raw` type is meant for data that is too complex to be easily represented with the other types. It will be written to the files directly as such, but still must be valid YAML (for pipelines/Ansible technology) or valid HCL (for Terraform).

### `widget`[​](#widget "Direct link to widget")

The widget attribute indicates the name of the HTML widget used to display the variable in Stackforms.

A wide range of widgets is available for standard values such as strings or numbers, as well as for handling specific entities such as Cycloid credentials.

For more details on all available widgets and how to configure them, refer to the next [Widgets section](/reference/stackforms/concepts/widgets.md).

### `description`[​](#description "Direct link to description")

The description attribute helps users understand the significance or impact of such variable/change. This supports markdown format, allowing you to easily insert bold, italic, or links into the description of your variable.

Here is an example of how you could use markdown in your descriptions:

***

* **Bold text**: `**Bold text**`
* *Italic text*: `*Italic text*`
* [Link](https://www.example.com): `[Link](https://www.example.com)`

***

* Code
* Widget

```
use_cases:
- name: Default
  sections:
  - name: Example
    groups:
    - name: Markdown
      technologies:
      - ansible
      vars:
      - name: Environment
        description: That's *markdown* compliant, you can have [links now](https://www.cycloid.io)
        key: mapped
        widget: dropdown
        type: string
        values: ["dev", "prod"]
```

![forms-markdown](/assets/images/forms-markdown-a49a95702c4b9cfc875b4c16e6eb89ad.png)

Also some emote using github format can be used

* Code
* Widget

```

...
      vars:
      - name: myvar
        description: "Type of Aws EC2 frontend servers :+1: :warning: :rotating_light: "
...
```

![stackforms-description-emote](/assets/images/stackforms-description-emote-6e78b8c9b9d9df3900785ed60d0dd268.png)

### `unit`[​](#unit "Direct link to unit")

unit attribute enables users to specify the unit to be displayed for a particular variable. This feature provides clarity and context, helping users understand the type of data they are manipulating.

Whether it's the quantity of servers, storage measured in gigabytes, or the number of users, specifying the unit ensures consistency and accuracy in data interpretation.

* Code
* Widget

```
use_cases:
- name: myusecase
  sections:
  - name: mysection
    groups:
    - name: mygroup
      technologies: [pipeline]
      vars:
        - name: "Disk size"
          key: disk_size
          widget: slider_range
          type: integer
          default: 5
          values: [1,10]
          unit: Go
```

![forms-unit](data:image/png;base64,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)

### `values` and `values_ref`[​](#values-and-values_ref "Direct link to values-and-values_ref")

The **values** attribute represents a list of allowed values within the context of the widget being utilized. The availability of these values depends on the specific widget employed.

This attribute serves to define the range of acceptable inputs or selections that users can choose from when interacting with the widget.

* Code
* Widget

```
use_cases:
- name: myusecase
  sections:
  - name: mysection
    groups:
    - name: mygroup
      technologies: [pipeline]
      vars:
        - name: "hello"
          key: hello
          widget: dropdown
          type: string
          default: "world"
          values: ["world", "you"]
```

![forms-values](data:image/png;base64,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)

The **values\_ref** attribute offers a way to specify a URL containing the values to display. This could be very useful if you want to create forms with dynamic values sourced from external JSON files or custom APIs. For more details, refer to the [Dynamic Values section](/reference/stackforms/concepts/dynamic-values.md).

### `default`[​](#default "Direct link to default")

The default value is the one that will be automatically selected when creating the project for the first time. It must respect the specified `type`. Once the project has been created, if you were to edit it, then the previously selected value would be retained.

#### Specification for `raw` type[​](#specification-for-raw-type "Direct link to specification-for-raw-type")

Variables of the `raw` type are considered strings to avoid YAML or HCL formatting issues.

Therefore, if you want to specify `raw` complex (multi-line array, map, etc.) default values, you have to use a YAML formatter to avoid unintended modifications. YAML offers several multi-line formatters (`>`, `>+`, `|`, `|-`, etc.), and the one we recommend using is `|+`.

This is because the `|+` formatter will write the string exactly as it is given, which aligns best with the concept of a `raw` variable.

While other formatters may work, you must be cautious with the one you choose, as it could slightly alter the output of the variable. For instance:

* `|` trims any extra unnecessary new lines at the end. If you leave 3 new lines, they will be replaced by one.
* `|-` strips any new lines at the end.

For more information, refer to: [YAML Multi-Line Formatter](https://yaml-multiline.info/)

##### Example:[​](#example "Direct link to Example:")

```
- name: "Ansible parameters (raw)"
  description: "Parameters of ansible-runner script (raw). Can be found here: https://github.com/cycloidio/cycloid-images/tree/master/cycloid-toolkit#ansible-runner"
  key: ansible_params_raw
  widget: text_area
  type: raw
  default: |+
    SSH_JUMP_URL: user1@Bastion1
    SSH_PRIVATE_KEYS:
      - ((ssh_bastion.ssh_key))
    ANSIBLE_VAULT_PASSWORD: ((raw_ansible_password))
    ANSIBLE_PLAYBOOK_PATH: ansible-playbook/
    ANSIBLE_PLAYBOOK_NAME: playbook.yml
```

This YAML configuration illustrates the use of a `raw` variable, where multi-line values are preserved intact, ensuring accurate representation and utilization within the StackForms environment.

## Special variables[​](#special-variables "Direct link to Special variables")

In addition to StackForms, Cycloid also offers a templating feature for stacks, providing a considerable amount of flexibility. This feature is elaborately explained in the [stack template page](/reference/stacks/concepts/templating.md).

As part of the templating system, Cycloid offers something known as Cycloid special variables. These are embedded variables provided by Cycloid, which you can utilize in all sample files and StackForms to access information such as `project`, `environment` (the name of the current Cycloid project/environment), `api_url` (The URL of Cycloid API for scripting purposes), and more.

To use these variables, you need to follow this syntax: `($ .variable_name $)`. For example, `($ .env $)` retrieves the current environment's name.

tip

For full reference on those variables, check our [stack templating section](/reference/stacks/concepts/templating.md)

## Let's recap[​](#lets-recap "Direct link to Let's recap")

* Code
* Widget

.forms.yml

```
---
use_cases:
# Each usecase is arbitrary and represent a meaningful usecase to you (aws vs gcp for example)
- name: myusecase
  sections:
  # Each section will be displayed in a different tab in the StackForms interface
  - name: mysection
    groups:
    - name: mygroup
      # This assign the current group to the technologies listed below
      technologies: [pipeline]
      vars:
        - name: "Pipeline variable"
          description: "Example of pipeline variable."
          # The key below will define the variable name in the chosen technology.
          key: my_pipeline_variable
          widget: simple_text
          type: string
          default: "mydefaultvalue"
```

![stackforms-variables-recap](/assets/images/stackforms-variables-recap-7caf453ac55ddf6fe7cc429313bab345.png)

* StackForms enables you to provision different [use cases](/reference/stackforms/concepts/forms-file.md#field-use_cases). For this example, we'll create only one.

* Next, you have various [sections](/reference/stackforms/concepts/forms-file.md#field-sections) that can represent any category you desire. Typically, they're used to separate variable categories like credentials, infrastructure variables, app variables, etc. These sections will be rendered in different tabs in the StackForms interface.

* Each section can contain multiple [groups](/reference/stackforms/concepts/forms-file.md#field-groups), often used to manage different technologies or group variables together.

* At the group level, you *must* add the [technologies](/reference/stackforms/concepts/technologies.md) where StackForms will inject variables. Then, we will declare our variables.

* Each variable must have a key, a widget, and a type. Refer to the [variables and widgets section in the file reference](/reference/stackforms/concepts/widgets.md) for a list of possible values.

* The key defines the variable name that will be injected into the technologies. For example, a StackForms variable with the key `my_var` can be accessed with `var.my_var` in Terraform or `{{ my_var }}` in Ansible.


---

# Widgets

<!-- -->

The `widget` attribute in StackForms allows you to define how your variables will be displayed in the StackForms interface.

A widget represents an interactive component for visualizing and inputting data within the StackForms interface.

We offer multiple widgets to cater to various needs, providing users with the flexibility to select the one that best suits their specific requirements. Such as slider range, dropdown menus, radio buttons, text fields, checkboxes, and more.

Each widget:

* Has its own allowed types (boolean, string, any, etc.).
* Can have value constraints (e.g., a slider range between 1 and 100).
* Can have a default value.

info

Some widgets are specialized for managing Cycloid entities such as credentials, service catalog, config repositories, ... These widget are prefixed with `cy_` in the widget name. Refer to [the Cycloid widgets section](/reference/stackforms/concepts/widgets.md#available-widgets) for more details.

## Available Widgets[​](#available-widgets "Direct link to Available Widgets")

This section provides an overview of all Cycloid widgets available. Refer to the reference section to learn how to configure and use each of them effectively.

<!-- -->

| Widget                                                                                          | Render                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [**simple\_text**](/reference/stackforms/reference/widgets/simple_text.md)                      | ![st](data:image/png;base64,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)<br />Simple field dedicated to text                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| [**number**](/reference/stackforms/reference/widgets/number.md)                                 | ![n](data:image/png;base64,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)<br />Simple field dedicated to numbers                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| [**text\_area**](/reference/stackforms/reference/widgets/text_area.md)                          |  ![ta](data:image/png;base64,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)<br />Multi-line text field                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| [**dropdown**](/reference/stackforms/reference/widgets/dropdown.md)                             |  ![dd](data:image/png;base64,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)<br />Menus display a list of options                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| [**auto\_complete**](/reference/stackforms/reference/widgets/auto_complete.md)                  | ![ac](data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAKEAAAB9CAIAAABFz5S1AAAAA3NCSVQICAjb4U/gAAAAGXRFWHRTb2Z0d2FyZQBnbm9tZS1zY3JlZW5zaG907wO/PgAAFLJJREFUeJztXWtsXMd1PmfmPvbF5WNJlpKoWGJCypUsK6IVPxU7VtoYRoM0LWSgaNE6RYwAVoIiKlrASZAAduPCgdMiL1swgspNnaLpA6gdOBHs2PGDkqVUdizZUiLH0YvWgxS5osnl7t7nnP4Y7vDug9Zy91KRl/eDQM3evXvn3vnuOXPOmTMz6DgORGhpsN/1DURYckQctz4ijlsfEcetj4jj1kfEcesj4rj1EXHc+og4bn1EHLc+Io5bHxHHrQ+t/lOJaL4MQMHPERoFAjBEAAQgAEDE0Kuol2NJKCIKIgAwdQ0w0gEhwfctz2OIiEhEodO8CDlGRCGEoWnI2JELF36Vzc66Xrh3s9yACJ2G+eHenjVdXZ7r+kRsCWjGesaPZa2+EDFdP5vLPXrokMG19ZlMm65D+Kpl2YAAACYt68jkRCYW/8LwZh1xKWiui2MAEEJomvbOTO6hX/ziLzesv2X16rDuIAII8V/Hjv3i/NgDW2/REWmuhw4N9coxAADifS+P3L1h/aa+voJlhXIfgogxBsvXekMCAqJ4LPbfv/71qenpv7/xBst2ZN8cVh119ceCKGYYPz91anVb26a+vrxl6Yw1aSAQEWNM0zTHcZAtR/OtZMYyIipa9l1XX/2ll146eXHqqvZ21/NC5LiuxiUiQnxzcvLGFX1CCF7LAiSac6aoBCh3tyouyDmfyc0+/cyLnHMhRBjP8j4DljUjEeLG7u7DExOM83DVWl0cIyIQzbpeZyyGROrOFJe+78vTfN9HREmbOqf6gkTEGSsUivtfPcQ5X86e9jzNRB2x2JRlq1YNC/UqSSWyWDKz5V/pUMViMcaYLCBiPp+XBSXr8r4l8QqMsUQ8vhQe4ZWAoFaDhVXa3MmlhgUkBKBQG2QR/vEcSuaAklHTNA8ePLhu3bp0Oj0yMvL44497nnfttdfu3LnT9315jqZpUj97nkdEsVgMAEqyHuLjXClQjMqAIAvKaxWkyoa5rzD0WNfijJ3qDhgRz549u3Pnzueffz6Xyz3wwAOf/exnH3nkkZ/97Gd79+7VdV0IgYjZbHZmZubVV191XRcAXnnllWKhYJimEAJazsUOxgQNxmKmCVW9W00skT5bvBwHIEXz4MGDMzMzL7/88o033rhr1641a9ZompZKpZRNoWnazp07u7q6XNfNZrNbtmw5duwtyyrc/w//qGnaXCyglYCIAJ4QccM4fvHij95660vXXy8AfCEYY5ff+GjIaSlJMGPMdd1Pf/rT69atu+eee1asWCEJfvTRR7u6urZu3WrbtmR6Zmbmk5/85K5duyYmJjKZzO7d/wIAe0dGUqkU0bwp3hpAIF+IuGGczeX++plnv/bK/r998SXOOWdMBKS5DCHTWoZLyLGsPegSSYtLBUAQ0fM83/cty5KxsCeffHLPnj1PPPGEtLHlm2uaZiqV8n1/zZo1/f39vu/39vTm83k0OxDnvIilfMzLCl8IjfO3L17885/89Gg2uzKZfOTw4aLn/dPtHzMQBVF1+Ail90ikwkFEoQ1DLchxWR1CzPEgCSm9d/J/xpht277vM8ZeeOGF3bt37969u6Ojw3Vdx3Ecx+nq6nIcx/M8znmxWLRtm3Nu2zZV+dOtAQQEAA3xn2+7LWXoviCGmHcd1/NihuHXelhpeRIilNwQGRcKhenaHFPA54GSfzwvxwDqdZMm1Uc+8pFvfOMbjz322Le//W1E/OY3v3n+/Pm7775bsn7//fen02nDMIiovb3dNE0iaku3mTGzKAQEHIzWgIwTrEmn13Z2zodppcITonbMQEpw6Z86R7HQDM2V8Wp16eB9+ELETOPBffu3Dw2t6+qUg53BRwKAd955p6+vz3XdQqEgjWfJq23bqVSqUCiYpinlWNd1zrnw/fHJ7L//z0+/vPNzlmWxlgtnUpVP/B4Rfhla2PPb347nC5/ZtKloW1qgQZoMG5fJcTXBSp0CYkLTZh2bqs6U5YGBAcdxDMNoa2uTdyOdY8MwfN9PJpNCCCFEIpGQhXg8zrmWz+cv6VG8f1HBSfUzzkcMAQBg1nGTuo44Z4VCuRw3THOlrq4meO44wUB7++sXLmzp73dt22Cs4j0tFosy5qUOBm/I87yKgm3bqWTiT/7oD6UiaUmOLwklQr4QSPSr7OT2oUHyfNV0wU6zYZrnOaby8HKwgIi2bd/+gdVfHhk5e3FqVVtq2rI4Y1jybbH8J1DrYwV8ANPUhzf9ftGycflxPNduiETkCdGRSr186pTr+xu6e4qOI52Ris64YZrL+uOaBEPpRUsYxv+dO/+vR47cd8P1azo6fNdtMkY1F+drIa9psSAAjsg0bf/Zs4+/eeRrN9/Uk0h4QqjxY0WnCp40IMdYrSqrCZbwhEgbxoFz5/7t6NGN3d0bu3tSuiZHuVvJu708UI08ZdkHx8fGCoUvDg+vbGuzPI8zhgHI09TwTwOxhHk5rmFnVY0XuZ6XMowZ235hdPT4u9NFz4vIbRhyGKJNNzZ0Z27t7wcAWwiNy9F5ZAGmoVx8G+R4IS0tbWAi8n3fNE1D1z0hNM4552E8ZoQ5uJ5HRJyxYrEog0WSZulSBqWZSkO69V+8tl2tIAkWQnieF4vFuKYxIjmiQq03YPS7gGxGXdOUSRWMAVc4KY3ZXHMcE5Ec5IeA/RYUZd/3lcYGAIwIDgnKJVGtLaPCigJZhtJpDdCsVfxyIYLlwEN13xAhRMggqO/7vNQrB0VZSrYUxUVRUBYwU+UKg0vq6uXmwv5OIJtamUHzirNcCBd1zbIuHcptLgX5ci3P7MnLDL+EoAQ3KV3zA1gSShsrRaHs6kiOLwNkz0jl+Y3BExroKCs5lpCXViE0ZV03cfMR6oKSK3VEeUoNy1ilrlY1QcDYiwi+bJA9MZSPqasuubFr1h61rfCSoekuIUKdqGj5UBp/wVwfFUirqK8CVD5a1Rgq0h6WMyps6VCc1Uvn3r53TWF5zBG7ElQKVYaoOBexVsR7y7Ea/G8Auq5HciwRDE2Hdc16OV7ozVIcz87OBuMvdXJGRJzzdDqtzPiI5tCxuPVAah6kwEiIsvLlwFQ9UTeS08zrOzlCA2hqLoyEHLsGAF3XpcbWdb1QKBBRMpmUOZo11YDU/6lUav/+/Yh4ww03qDmuFR5hMEAfrLf5m18OCIFjpa5HR0dXrVrFOX/jjTfGx8d93+/v79+wYYOiWTLEOXcchzGm63qxWGSMzc7OKvKUAgiOt8iPFdU1f+fLBCFwDACIODY2tm/fvm3btmmaduLEiTvvvNNxnGeffXb16tWpVEq69vl8nohmZmZWrlxZKBSy2WxfX59lWTfddJPUBJzzvXv3xuPx6667zrbtqakpmZw7MDBw5MiRbDb70Y9+NJjPFqEehMMxEU1NTRHR+Pj40NDQxz/+cdM0XdflpYwRRHRd97nnnuvv78/lckePHu3u7p6enj527Nhdd9319a9/XdO0++67b8eOHclkMpvNDg4O7tixY/v27UNDQ/fcc8/IyIh8XZ544onvfve7cqZF66XdLxFCaCapNgcHB9Pp9Pr16w3DiMfjiHjgwIG1a9em02nlViHixo0bt23bNjU1NTAwcMcdd+RyuWKxqGlaZ2fnoUOHxsbGHn744e9973vpdHpmZkbX9ccee2x4ePgHP/jBd77znYceesjzvKefflqlM0SoByFwLNWm67pEJP8ahrFv375YLLZ582bLsjjnUsFqmgYAnuel02nOueu6hmG4rouIuq6Pjo5+6EMfIqJEIvH5z38eAFKplK7rZ86caW9vz2QyQogNGzaMjo4u5KxHqIlw5Fhawq7r+r6v6/rBgwcLhcLNN98sJ09YliUnIqtEA/kqyCPyby6X27hx4+uvv+44zsmTJx988EEAkAlsq1atKhQKr732mhBiZGRk8+bNynyLUA9C850SiURnZ+fhw4c3bdp08uTJrq6ukZER27a3bNly7tw5zvnQ0FAymZRvQyqVkpKdSqWIqKenRwixdu3aT33qU/fee6/nedu3b0+n03Kmcjwe/8pXvvKtb31L1/Vbb7319ttvD5rZES4JdByHAtkkVJXG5TiO67q5XK63t7e7u7vCppUfhRC5XM73fTmtDQLzmmRqEgSiJepXUFqisa2tjUoLE0xNTZmmKae+QSmJCREdx8nlcplMplWjnvIxz5w5k8/nk8mkruuGYWiapvJwoXJJr3rRrByrflEmA0mLFwB0Xa84QZRPvQ0WVJ6p7/udnZ3yatIgl8/j+75hGJlMJpiz2Ho0LxGa5VjFpKQsNnaF4FCaLAcXZlMvAQCw0uz6iOD6EQLH8q8S3LAQsRgWQtDVUY7AFY7Q5DiU60RYCkQeSOsj4rj1sbi9f6Ig4tIhlBTMmlhEPldYaYIRFoJq4XCxiHwuNUM14ngpQIHpweFiERzLuKaaoRohXMgkOJntFC4WrauXSJ9EgCXT1YveayDC+w6R79T6iDhufUTx6tZHFK9ufYQmx3KFg8VSJX8idwaCANNB9VBRiN6GxSI0jmU+XpAkqG9Om9x1cYHz1bK6IjIdGkYIujpIrfoos7pU/uV7XwGqJBgRgQi5CcjAt9BoA7cIVBZiey9ZB4BI3EsIJ79a5XCphVlPnz596tQp9a2EWjsm+BHkZgrCJ+GR8OfO9x3SNHFij//G94GY//zfkD1NgCR8ACASRAIASPhAAsgnEqqApWXdI0iEk18t861++ctfyiz5F198cXR09MSJE/v27QuKuGEYhmEkEgnOua7rskBECALNNCbb0WwjEggAZjuaJuRO09kXwYzh4J8SN9BIgBYDItQTqCWQcTTbMNaGiTQyHWNtmEwj06NJbxUIZ94iY+ztt98+cuRIMpnMZDKc89tuu8113aeeemp6erqjo0Om8Y6OjiLixMTE0NBQPp8fHR0dHBzMZLpIS9LxH4vTL7G1f4BrPkEkxK9+CPmzkDuPsQwIj4pZxmPi7SexfQ30rBfvjABy7PggndtHnkVTv+Ef3iHeepYmj/HN90Kil3x3ee6pXBOhzYWJx+PxeNw0zc7Ozq1bt/q+f+HCBbkpnxzGIKIDBw7kcjnDMPbs2TMxMZFIJPaOvORign7zn+LN77PBO/2DD9H4a3T8x+LVh6F9tbjwGgCB44mX/w5I+G8+Ks6/AoYhjv+vOPFjcma85z6HTIPCuPejW0EIcGf9n38BuC4Hu5t/tNZAaHNTV6xYEY/H+/v75cdisXjgwIHh4WG5/Y/Uyclk8uqrrzZN8/jx4wMDA5lM5vTpkzMzud63/4N4gqwL4Lp0+lmaPsmHv8iu+QvIX4TJw8AQ410EgEYbcpOEQC0OPIbks+6N7No/w97N7vn9fNNnaOYO76k/Butd1OJCRONjcwhNocm1ztUslZGRkWuuuWZwcNBxHF3XtdL6zK7rWpZlmqbv+1axyDkH4YHvYdtqJM6u28k2/BXlxyDRAwDANEC5GDoiMhICuImMAY+V3Cogxycnh/EMWUVycsgNEoKiwbEAwrG55JSWYrE4OTkJAM8884ymaT09PSdOnBBCjI+PT0xMyP33AAARLcsCAMaZY9sCNbZ6G+XP4Ac+hkYC9DZccYN/eJcYOySOP0m+BQRkTyEQdlwtTvxEjB0SJ58m4ZPvkT2NjAMRWVlgHADInlJ31fyjtQb4V7/6VVmqcD2VeyNzPxzHicVi8Vrbjsu+Vo5vZ7PZjo6ObDYbj8fHx8cnJye7urqmp6cdx8lkMsVisa+vjzHmOE5vb6+maZbt9GbSiQ/eTu+eEm/+kArnWe8wu+oTlH2TTr/E+q7H3mHWOQT2u/h7W9jKm+jcXrpwlK3ait3XsPRVIBy28hbwbSCPr7wFyAOvyFbegozD+zA+KpfNkBN/5PR8ud1AMMuqgeBxvXPaZmdnOzo6Ojs7K/JApHKWL4F0nOQtqpQgz/Ok9vY8T842JiJV0DSNSGiaDkYSBKGG4NhAPpiJudCWJ8C3wEiQU0DkoJtzq/P7PggXtBg4eWB8roAM9Di4hbn9ON5XkHIyNjZm2/aVNadNVSn7WlmQOlmdIOcwIqLjOPIEVZDrSSCAsKYBEVyY64CLMwAIQIAMAcmaQeREHli2Og6AYOeQcRL+XIEE2DnAaNJbGcKZfyxFs6lLME0VAYCAqysDImJpS43AcUSUL0R1Ad6HinrpcIWOLQajYzUriiisH1GOQOvjCpXjCCEiCuq2PiKOrywo9zXEGM6lOV66uVYRqlEzytFk49e1Dj2UD/U3U1+EhaDatprjJo2VBTkOcinLmqbJ0YXIPloKUGn1qtBlaX6/xYovMLCQlixzztXwUVjVR1BQHEOg8eVXIchx9SWU1xsMhUe6ekkRZFRBGUPN0Fx7v8VgFFp9FYnvZUBFg1cYQ9CQ/aVV/KxCfKH8tapgPUKIqG5tqIoAUkN7487bXEFdoa6iKtN1PZvNnj9/vlAoWJYlt0OO9HaTUIaOruvxeDyRSEjDFqqEWH1sQG/P9cdqGLjiDiQYY3ITCNu2LcuyLEsuYxxx3DAUbYjIOZftL61alRcAVX1zY0p0fkSPak13AABWgmEYchw7Ho/LfZghipA0iiCFcjaQruumaSqOFc0UWC5USeOi6prnOCjK6sWRR+QrJrt9RNQ0rWIT5ggNQ3KsaFYpPtUdMwQkqsH+WMluMOCiFLVS45J1NZ8lxKddhlCaUmpshWAaV7WKbaQ/hvIXBMvNd7UVhKKcAtshRzQ3iQqjp4JmaM6ilijLsKmoG0rrRasjSmlXc9yYObA8UdFoQeNL/g0KsTqzWgLrRJnvhLWmemIgwBaMpioFEqVwLBbVgqHauaIQ7Iyh0Vn2tftjKFcRFf5ZsMOOCG4MFfFEWDjW1CTBUD3uVJPmYOcPUR+8NAgyLY9UdJTN+sfBaipoxpKl3VhnEKEBVFu+zQxL1Bg/Dl6RSjt1VHhKkYoOC9UtGVSZQQFruIraOQILqeuKMccIzaNmdxuuPbtgHkiwDqhlI0QIF8EuEkLVlJfI51J1BO8gsrmWCEukJhexfjVEHfBlQeiNHOVXtz4ijlsfEcetj4jj1kfEcevj/wH5P4SHBcVdTQAAAABJRU5ErkJggg==)<br />Provides suggestions while you type into the field                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| [**radios**](/reference/stackforms/reference/widgets/radios.md)                                 |  ![r](data:image/png;base64,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)<br />Graphical control element that allows the user to choose only one of a exclusive options |
| [**switch**](/reference/stackforms/reference/widgets/switch.md)                                 |  ![ta](data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAGMAAAA0CAMAAACpbnboAAAABGdBTUEAALGPC/xhBQAAACBjSFJNAAB6JgAAgIQAAPoAAACA6AAAdTAAAOpgAAA6mAAAF3CculE8AAACMVBMVEX6+vr5+fn4+Pj39/f29vb19fX09PTy8vLz8/Px8fHw8PDv7+/u7u7t7e3s7Oze5+ep0NBptrZPq6scl5fr6+uOxMQpnJyPxcXO3t5CpqbB2NjY6uq33NyWzc18wMBzvLxyu7tyurpyublxt7dutLRusrJgrKwhmJjM3Nzq6urw9PSdz890vb1vtbVus7NrsLApm5tBpaXn5+fh7++ExMRssLBHoqKKwMDo6Ojx9fWFxcVwtrZtsbFlra0gmJgom5vW39/p6eme0NB0vr5sr69Qo6OhyMjZ6+ttsrJqrq43nJxYq6vj4+NxuLhts7Npq6sumpo8oKDg4OBrra1nqKgimJjd3d3k5OR8wcFrrKxmpqba2tp7wMBqq6tmpKQgl5fY2Njh4eFzu7tlpKQtl5c0mprX19dlo6M0mJhJoaFvtLRssbFJmZmCs7Oe0dFxublbm5sfl5fBysqExcVqrKxlpqZhnZ0/lZV2rq7R0dHZ2dni4uKDxMRnp6dioaFemJgmlpY1nJzIyMjT09Pb29ud0NBrr69oqalko6Ngm5tSlJQflpYlmZmsvLzMzMzW1tbe3t7m5ua229uVzMx6vr5prKxmpaVhn59NkZGgt7fOzs7ExMSmtrbU1NTLy8vDw8O8vLxyqKjl5eXS0tK/v7+ut7eDqqpToKBAnJwkmJjGxsbBwcG9vb27u7u3t7e2tra1tbXf39/V1dXPz8/KysrHx8fCwsLAwMDc3NzJycn///+atjsMAAAAAWJLR0S6o7FH2gAAABBjYU52AAARgAAABaAAAALVAAACg0A2dzMAAAP7SURBVFjDtdjpfxNFGAfwhLSbvaHsEgGLAQpiIAkarC6kHktRpKRUImSBcPTQcKl4ANpUrbb1riFVuZqm0AClnKUHtPx3zMxudpN096PZWX4v2nf7/TzPbHbmGZerqrgXxuVk3NZ5/oJDivu/4yyxqBgnEbPnmzjOEOpjPcVUKg4QBlADYzDYSCmhP78YjcFESotQgVoQgiDgP5UpLQXHUIuAAHi8Vw2CUC0GgktAgSQpii6GokhSVbAQ3UAEgQSG5Xie51gGKYSG2DbKCIL0UjTDLV5St1QQhKV1SxZzDE15SQIPMToFCVADJy7zCcX4XhA5UAtC9G7ZNkAZkOD45SuE0qxYznMIMQrBJcSVPqE8vpUiJuJ2v1i/6iW/3796zdqGhnXrX94gVMb3SoClvGDh7RobNwWDQUD4IREKb35VWJjXIiIDEb2Q6ogtrwdVA5YRCje+IZjlTYlnSgupiti6LagZgIiua3rrbVPjnXdljoaF2DG2NweNVkXDO94TzPN+hKdLmlUNsbO5xIiGPtjVYmHsjgVY2p5R36y3ak1rdM+Otg8tjL3xCEeDD5eNZq0yjLXR6J6P9lkQwv6EwjOUrQU5UGY0HTxkZQjJmGzTOFxqhBqPHLUijrV3SKw9Q+9Vp2p0fWxhfJJSjZrqjfoK4/gJC+NkKi7BF8uGsdMwWqOnTh/p+tTC+AwY8MWyYbg+140zDadOt3V98aX5a/UVWA/OXq9cW7/WjE5onD13/htT49vudI8M1qOmpvrfIPgmfoeQTtAs8DP//ofeH02In/r6B5QA44UfRVvf9p8140wo/Muvv/3+x58LiMG/MheyQzxN2DXAHvX3P//CZkXDjRcvXe69UokMXu3rTvaAJddbVb2B9lqw01KsrCQuDOdGyj+MLSO54VRCQcvhsbvXakYtSfNSRzI/eu362KBRxNj1a6P5ZIfEwzcX04CFMGIhnr4xmrt5a/z2xB3hzsTt8Vs3c6M30vGCCPZBeGjAOpigQkC3sun+zN179x88nHw0+fDB/Xt3M/3pLOgURhn6OdEDEYaTlKnk9Mzs49yTubm5J7nHszPTySlF4hhIeDAPo+BoXkt4WV4qxOfb8zPDmad9TzPDM/n2+XhB4lm00Xpwz9QqwvDyUM/UfDo1ne/PT6fS81M9QzI6lHgwytAP1SoCTopSIRbPJhIDiUQ2HitIonok0RccawBBCEkxvChHCooSU5RCRBbBHktiE2UIGkBYThQDATkQEEWOReMHNmEMhCqCJgQGBk0F5QT2YKtNhEAhSTANgr8EoU2Dzg3oxblTHW21odazyAmi4hageAmgXwE4dSvzP+5LXNgxufl5Dtdk9i+vngHh2PGQF4z9wAAAAABJRU5ErkJggg==)<br />Choosing between 2 positions `on/off`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| [**cy\_cred**](/reference/stackforms/reference/widgets/cy_cred.md)                              | ![cred](/assets/images/credentials-5665fc04264847f55220d6545406739f.png) <br />Expose cycloid credentials available                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| [**cy\_inventory\_resource**](/reference/stackforms/reference/widgets/cy_inventory_resource.md) | ![inventory](data:image/png;base64,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)<br />Select a resource attribute from the inventory and link the value to this asset                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| [**slider\_range**](/reference/stackforms/reference/widgets/slider_range.md)                    |  ![sr](data:image/png;base64,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)<br />Select option by dragging a slider along a range                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| [**slider\_list**](/reference/stackforms/reference/widgets/slider_list.md)                      |  ![sl](data:image/png;base64,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)<br />Select option by dragging a slider along list of options                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| [**cy\_scs**](/reference/stackforms/reference/widgets/cy_scs.md)                                | ![scs](/assets/images/scs-83a234b059fb33df1b242ae62fe2afff.png)<br />Expose cycloid catalog repositories available                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| [**cy\_crs**](/reference/stackforms/reference/widgets/cy_crs.md)                                | ![crs](data:image/png;base64,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+OCDu3btkiTp8OHDNptt3LhxBw4cCAQCixcvDgQCH374ISGkoKBg7ty569aty87OjoqK+uKLL7Zu3Wq32+Pj471e7/Tp010u14svvrh06dJTp07V1tbSNL179+6f/OQnLMuePHnyq6++OnPmTFxc3KJFiywWy2uvvTZhwoSbb75ZluX169cPHjx43LhxNE2XlpYePXq0vr5+wIABc+bMMR5BaJoWRfHf//53U1MTISQ2Nra4uNhutx87dmz79u2CIASDwR//+Mf5+fmNjY2vvvpqZmbmuXPnmpubJ0+e3N7efuLEic7OzuLi4tzc3FOnTm3fvv2+++5zOp3/+c9/Dh8+HBcXRwihaRo81g0bNlRWVtI0bbFYFixYEBcXt2vXrra2NqvVWllZabVaFy1aFBMTEwgE1q9f39DQ4HK5GIax2+2zZ89+9913W1tbLRZLa2srTdMrV67UNG3jxo3QIZGRkfPmzbNYLIQQURQrKipmzZql67rX6920aVNHR4csy1lZWbNmzRIE4dChQ3v37uV5XpKk2267LTs72/DBd+7cKUlSeXm5w+EYP358VVXVO++8QwiRJGn69OmDBw9ua2vbtGmTx+NRVTUlJWXevHn79u1rb2//8ssvo6OjJ02aBI810KtvvfVWfX09tIJhmLvuuqukpITjuDFjxuzbt4+iqG3bts2ePTshIcF4bkMQ5FrSfVweQhAVFRX79u1buHDhsmXLGIY5f/48RDZ8Ph9FUbfffntYWFhhYeG4ceNkWT569Choweuvv+71epubm9evX2+322NiYqqrq1VVLSkpGTly5KOPPpqTk1NdXQ366Pf7g8Hg2LFjb7rppoyMjOLiYkIITL0WFxc/8sgjjY2NR44c4Xne5/MZMRm/3w9RBVmWbTbbokWLli1bduzYsbKyMgjuE0I4jtu5c2ddXd0vfvGLFStWNDQ0lJaWiqK4cePGMWPGPPzww5MmTdq8ebPX6+V5vqmpKS4u7sEHHxw7duy6devsdvvKlSuzs7N37NihKIrb7Z4xY4bdbq+srNy7d++dd955//33u1wuWZbBtW9qalq+fPmTTz6pquqHH35IUVRnZ2djY+O0adNWrVql6/r+/fsZhvnwww/r6+tXrlw5f/58r9fb0dEhCMLcuXOXLVu2YMECSZJuvvlmi8Wye/fus2fPLl++/KGHHmpvb3/v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)<br />Expose cycloid config repositories available                                                                                                                                                    |
| [**cy\_branch**](/reference/stackforms/reference/widgets/cy_branch.md)                          | ![branch](/assets/images/branches-59f86e6f2c445e3a8728acfb0a6068ea.png)<br />Expose branches available from `cy_scs` or `cy_crs`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |


---

# YAML Anchors and Aliases

If the [common use case feature](/reference/stackforms/concepts/common-use-case.md) (`cycloid-common` use case) isn't sufficient for your needs, you can still leverage YAML's native features to tailor your configurations.

To reduce redundancy and streamline your [.forms.yml](/reference/stackforms/concepts/forms-file.md) definition, YAML Anchors and Aliases can be employed.

Items can be identified with an anchor and then referred to by an alias later in the `forms.yml`. Anchors can be reused by multiple aliases, offering a more concise and organized YAML structure. Anchors are denoted by an `&` character, while aliases are indicated by an `*` character.

Consider the following example: my stack comprises 3 use cases. Both **A** and **B** share the same `section FOO`, but **C** is different.

Below is a sample `.forms.yml` demonstrating the use of anchors to add a `FOO` section in both **A** and **B** only:

.forms.yml

```
# YAML anchors
shared:
- &foo-section
  name: FOO
  groups:
  - name: Group1
    technologies: [pipeline]
    vars:
      - name: Widget1
        ...

use_cases:
- name: A
  sections:
  - *foo-section

- name: B
  sections:
  - *foo-section
```

Anchors and aliases can be applied at any level within your `.forms` file, not limited to sections. For more advanced usage, refer to the [YAML documentation](https://yaml.org/spec/1.2.2/#alias-nodes).

warning

If you want to use the YAML Merge operator `<<:`, you must quote it or you will get an error.

This is unfortunately a limitation from our side that will be fixed in the future:

```
# YAML merge
shared:
- &foo-section
  name: FOO
  groups:
  - name: Group1
    technologies: [pipeline]
    vars:
      - name: Widget1
        ...

use_cases:
- name: A
  sections:
  # Quote the merge operator or it will fail
  - *foo-section
```


---

# File reference example

* Code
* Result
* Demo

.forms.yml

```
---
use_cases:
# Use case definitions must match those in your .cycloid.yml file !
- name: "use-case-A"
  sections:
  # Sections are just logical entities
  - name: "section-A"
    groups:
    # Group serves as logical grouping entities and
    # will allow you to select the technology configured
    # by the stackforms variables.
    - name: "This group uses the pipeline technology"
      technologies: [pipeline]
      vars:
      - name: "Auto complete"
        description: |
            Only `string` allowed.
            Values listed here are suggestions, user can input arbitrary values.

            # Note that _markdown_ is supported in `description` block.
        key: "auto_complete_var"
        widget: "auto_complete"
        type: "string"
        values:
        - "one value"
        - "another one"
        - "maybe"

      - name: "Drop down menu"
        description: |
            Type can be anything but raw
            Must have at least 1 value, only 2 if `boolean`
        key: "dropdown_var"
        widget: "dropdown"
        type: "string"
        values:
        - "value1"
        - "value2"
        - "value3"

    - name: "This group uses terraform technology"
      technologies: [terraform]
      vars:
      - name: "Number input"
        description: "Type can be `integer` of `float`"
        key: "number_var"
        widget: "number"
        type: "integer"
        default: 42

  - name: "section-B"
    groups:
    - name: "This group uses 2 technologies"
      technologies:
      - "ansible"
      - "pipeline"
      vars:
      - name: "Radio buttons"
        description: |
          Type can be anything but `raw`
          Must have at least 1 value, only 2 if `boolean`
        key: "radios_var"
        widget: "radios"
        type: "boolean"
        values:
        - true
        - false

      - name: "Simple text input"
        description: "Only `string` allowed"
        key: "simple_text_var"
        widget: "simple_text"
        type: "string"
        default: |
          Some text value

- name: "use-case-B"
  sections:
  - name: "section-A"
    groups:
    - name: "group-1"
      vars:
      - name: "Slider list"
        description: |
          Type can be `string`, `map`, `boolean` or `integer`.
          Must have at least 1 value, only 2 if `boolean`
          Values of type `map` will be redered as
          `JSON`, `YAML` or `HCL`
          depending on the technologies used.
        key: "slider_list_var"
        widget: "slider_list"
        type: "string"
        values:
        - "one"
        - "two"
        - "three"

      - name: "Slider range"
        description: |
          Type can be only `integer`
          Only two values accepted, minimal value first, maximum second.
        key: "slider_range_var"
        widget: "slider_range"
        type: "integer"
        values:
        - 24 # min
        - 48 # max

      - name: "Switch button"
        description: "Type can be only `boolean`"
        key: "switch_var"
        widget: "switch"
        type: "boolean"

      - name: "Text area"
        description: "Type can be anything, `raw` included."
        key: "text_area_var"
        widget: "text_area"
        type: "map"

      - name: "[BETA] Inventory widget"
        description: "Select a resource attribute from the inventory and link the value to this asset"
        key: "aws_vpc"
        type: "string"
        widget: "cy_inventory_resource"
        widget_config:
          attribute: "id"
          filters:
            attributes: 'tags.env[eq]=infra'
            type: "aws_vpc"
```

![Redered StackForms example screenshot 1](/assets/images/widget_forms_yml_full_example_1-f45f7258df6f1594838c9bb454beef49.png) ![Redered StackForms example screenshot 2](/assets/images/widget_forms_yml_full_example_2-25488c1942ceff2a29396aee2a3c953b.png) ![Redered StackForms example screenshot 3](/assets/images/widget_forms_yml_full_example_3-2aac3aca515e8618d34ae02d2d7744df.png)

![Redered StackForms example gif.](/assets/images/widget_forms_yml_full_example-04e6633f7560439a21b74f0fc261cadb.gif)


---

# Manipulate Stackforms environments using the CLI

Starting at [Cycloid CLI version >= 5.0.49](https://github.com/cycloidio/cycloid-cli) you can now manipulate environments in projects using Stackforms.

warning

The command `cy projects create-stackforms-env` will `cy projects create-env` in the future.

The alias `cy projects create-stackforms-env` will stay in the future, but old script using the old `cy projects create-env` command will have to switch to `cy projects create-raw-env` or update to use stackforms.

see [this issue](https://github.com/cycloidio/cycloid-cli/issues/268) for more information.

## Create an environment using stackforms[​](#create-an-environment-using-stackforms "Direct link to Create an environment using stackforms")

```
$ cy projects create-stackforms-env --org myOrg \
  -p myProject -e myNewEnv \
  -u stack-usecase \
  --var-file /path/to/json/var/file \
  --json-vars '{"section": {"group": {"myVar": "foo" }}}'
```

The output will be the new environment configuration as understood by the backend.

## Read environment config (require stack using stackforms)[​](#read-environment-config-require-stack-using-stackforms "Direct link to Read environment config (require stack using stackforms)")

This command allows you to fetch the current config of an environement using stackforms.

```
$ cy --org myOrg project get-env myProject myEnv
{
  "section": {
    "group": {
      "var": "foo"
    }
  }
}
```

The output format matches the input format for `cy project create-stackforms-env`, allowing you to easily duplicate an environment by piping the output.

```
$ cy --org myOrg project get-env myProject env1 \
  | cy --org myOrg \
    -p myProject -e myNewEnv \
    -u stack-usecase \
    --var-file "-" # if '-' is given as filename, this will read from stdin
    --V section.config.fooVar=bar # You can override the previous config using -V or -j vars
```

Lookup the help for more informations

```
$ cy projects create-stackforms-env --help
Create or update (with --update) an environment within a project using StackForms.

You can use the following ways to fill in the stackforms configuration (in the order of precedence):
1. --var-file (-f) flag       -> accept any valid JSON file, if the filename is "-", read from stdin (can be set multiple times)
2. CY_STACKFORMS_VAR env var  -> accept any valid JSON string (can be multiple json objects)
3. --json-vars (-j) flag      -> accept any valid JSON string (can be set multiple times)
4. --var (-V) flag            -> update a variable using a field=value syntax (e.g. -V section.group.key=value)

The output will be the generated configuration of the project.

Usage:
  cy project create-stackforms-env [flags]

Examples:

# create 'prod' environment in 'my-project'
cy project create-stackforms-env \
  --org my-org \
  --project my-project \
  --env prod \
  --use-case usecase-1 \
  --var-file vars.yml \
  --json-vars '{"myRaw": "vars"}' \
  --var section.group.key=value

# Update a project with some values from another environement
# using -V to override some variables.
cy project get-env-config --org my-org --project my-project --env prod \
    | cy project create-stackforms-env --update \
    --project my-project --env staging --use-case aws \
    --var-file "-" \
    -V "pipeline.database.dump_version=staging"

Flags:
  -e, --env string              environment name
  -h, --help                    help for create-stackforms-env
  -j, --json-vars stringArray   JSON string containing variables, can be set multiple times.
  -p, --project string          project name
      --update                  allow to override existing environment
  -u, --use-case string         the selected use case of the stack
  -V, --var stringToString      update a variable using a field=value syntax (e.g. -V section.group.key=value) (default [])
  -f, --var-file stringArray    path to a JSON file containing variables, can be '-' for stdin, can be set multiple times.

Global Flags:
      --api-url string     Specify the HTTP url of Cycloid API to use eg https://http-api.cycloid.io. This can also be given by CY_API_URL environment variable. (default "https://http-api.cycloid.io")
      --insecure           Decide to skip or not TLS verification
      --org string         Org cannonical name
  -o, --output string      The formatting style for command output: json|yaml|table (default "table")
  -v, --verbosity string   Override the default verbosity for this command. VERBOSITY must be one of: debug, info, warning, error, critical, none. (default "warning")
```


---

# Introduction

The `.forms.yml` file allows for the creation (or update) of a project via a nice interface, enabling easier and more controlled configuration of stacks. This includes restrictions on provided values, exposed variables, range, etc.

The Stackforms interface simplifies stack creation for all users, with the following documentation primarily addressing stack creators and explaining how the feature works and how to use it for a stack.

**How does it work?** This feature relies on a configuration file (` .forms.yaml`) present in the stack source code. When this file is present, Cycloid switches to stackforms mode and displays stack configuration via an HTML form.

![](/img/stackforms-overview.png)

Basically, the `.forms.yaml` file's goal is to define the mapping between stack parameters (IaC) and a human interface. The file describes each parameter and how they have to be displayed to the user.

**Under the hood:**

The `.forms.yaml` is the middle key component. For a user connected to the Cycloid console, during the configuration of a project, an HTML form is displayed. As mentioned above, the definition of this form is contained inside the `.forms.yaml` file.

![stackforms-overview-details](/assets/images/stackforms-overview-details-39da8aec6de987ad9ae54e614fa1f3de.png)

Cycloid console exposes parameters to the user, who will have the capacity to change them accordingly. Once everything has been fulfilled, the data will be sent back to the Cycloid API, which will validate the user's input based on the `.forms.yaml` file definition.

If all user inputs are valid, StackForms reads the defined sample files described in [.cycloid.yaml file](/reference/stacks/reference/cycloid-file.md) under `config.$technologie.path`. StackForms then renders these sample files, adding or updating parameters with the user inputs. Only the elements defined in `.forms.yaml` will be replaced in the sample file; everything else present in the sample file will remain unchanged.

And render the user's inputs and mapping defined in `.forms.yaml`.

In the final step, the generated file from user input and sample files is written into the selected Git Config Repository of the project automatically.

## Prerequisites[​](#prerequisites "Direct link to Prerequisites")

The only requirement is to create a `.forms.yaml` file in a stack.

Important

When using Stackforms in a stack containing several use-cases in your `.cycloid.yml` file, ensure that all the use-cases are defined in the `.forms.yaml` definition. For details, please refer to the [Forms File Format section](/reference/stackforms/concepts/forms-file.md).


---

# Quickstart

This quick start section provides a "Hello World" example by adding Stackforms to an existing private stack.

note

To start a new stack, we recommend using Cycloid's [stack blueprint](/reference/stack-blueprint/.md) feature, which already includes all the basic file contents and a simple Stackforms configuration.

## Context[​](#context "Direct link to Context")

The Stackforms configuration file is bound to the stack configuration defined in the `.cycloid.yml` file. Let's take the following example:

.cycloid.yml

```
name: 'Dummy stack'
canonical: 'stack-dummy'
...
config:
  default:
    name: 'default'
    description: 'Default pipeline usecase'
    pipeline:
      pipeline:
        path: 'pipeline/pipeline.yml'
      variables:
        path: 'pipeline/variables.sample.yml'
        destination: '($ project $)/pipeline/variables-($ environment $).yml'
```

As mentioned previously in the prerequisite section, each stack use-case has to be defined in the `.forms.yml` file. In our example, we can see one **use-case** *(line 5)* called `default`.

Then, as explained in the introduction section, Stackform uses a sample file to render and write variables. In the current configuration file, we defined `variables.sample.yml` located in the **technology** `pipeline` *(line 11)*. Technologies will be defined in more detail in the [.forms file format](/reference/stackforms/concepts/forms-file.md) section.

## Configuration[​](#configuration "Direct link to Configuration")

Based on the context above, here is the `.forms.yml` file you can create in the stack git repository, next to the `.cycloid.yml` file.

![stackforms-quickstart](/assets/images/stackforms-quickstart-d2cec793a7e3c496cfca69247e89e926.png)

.forms.yml

```
use_cases:
- name: default
  sections:
  - name: Global configuration
    groups:
    - name: User message
      technologies: [pipeline]
      vars:
      - name: "Message"
        description: "The message to display"
        key: message
        widget: simple_text
        type: string
        default: "hello world and especially to ($ organization_canonical $)"
```

This Stackforms configuration file defines a form for the default use case *(line 3)* and displays a text widget where the value will be written into a variable named `message` in pipeline technology samples.

The result should be the following file created in your config repository:

myproject/pipeline/variables-myenv.yml

```
message: hello world and especially to ...
```


---

# Editor

Writing a StackForms file can be a lengthy and sometimes tedious process, involving back-and-forth between your Git repository and creating a project with such a file.

Now, this process is much simpler with the StackForms editor!

You can directly edit a file, validate it, and preview how it will look when used. This means you can also test conditions directly within the interface.

## Interface[​](#interface "Direct link to Interface")

You will find the StackForm's editor under `Stacks > Tools > StackForms Editor`. There you will find the editor which is constituted of 2 panels:

1. The left hand side which is where you'll be able to edit the file in YAML
2. The right hand side which is the visual rendering of your file

To display the visual rendering of the file, you need to ensure the file you've written has a valid format by clicking on the `Validate` button first. New changes will follow the same rule. If you're happy and/or wish to copy/download the file, two buttons are provided for this.

![Stackforms-editor](/assets/images/forms-editor-db4de22535b126478fec72421ef7691f.png)

A few sample files are also provided to help you get started, if this is the first time you're writing a StackForms file.

![Samples](/assets/images/forms-samples-1432934ff00f5b7515dec0cca1d3bdf4.png)

## Using Cycloid CLI[​](#using-cycloid-cli "Direct link to Using Cycloid CLI")

Another method to validate a `.forms.yml` file is by using our open-source CLI. With our CLI, named `cy`, you can validate the format of the forms file directly on your computer. This provides a convenient way to ensure the correctness of your StackForms configuration locally.

```
cy --org cycloid stack validate-form --forms /path/to/your/.forms.yml
```


---

# Types

What widget are available depending on the output type you need.

## `string`[​](#string "Direct link to string")

* [simple\_text](/reference/stackforms/reference/widgets/simple_text.md)

  * Allow arbitrary values

* [text\_area](/reference/stackforms/reference/widgets/text_area.md)

  * Allow arbitrary values

* [cy\_cred](/reference/stackforms/reference/widgets/cy_cred.md)

  * Pre-Defined values
  * Output the credential path for the associated technology

* [slider\_list](/reference/stackforms/reference/widgets/slider_list.md)

  * Pre-Defined values

* [cy\_scs](/reference/stackforms/reference/widgets/cy_scs.md)

  * Available catalog repositories in cycloid

* [cy\_crs](/reference/stackforms/reference/widgets/cy_crs.md)

  * Available config repositories in cycloid

* [cy\_branch](/reference/stackforms/reference/widgets/cy_branch.md)

  * Branch of a catalog or config repository

* [cy\_inventory\_resource](/reference/stackforms/reference/widgets/cy_inventory_resource.md)

  * Available resources in [Cycloid asset inventory](/reference/inventory/.md)

* [auto\_complete](/reference/stackforms/reference/widgets/dropdown.md)

  * Allow arbitrary values
  * Compatible with [`values_ref`](/reference/stackforms/concepts/dynamic-values.md)

warning

If you want to use value mapping, you need to set the `type` field to `map` instead of `string`.

Your code will receive a string corresponding to the `value` of your mapping.

See [this section please](/reference/stackforms/concepts/value-mapping.md)

* [dropdown](/reference/stackforms/reference/widgets/dropdown.md)

  * Pre-defined values
  * Compatible with [`values_ref`](/reference/stackforms/concepts/dynamic-values.md)
  * Allow the use of [value mapping](/reference/stackforms/concepts/value-mapping.md)

* [radios](/reference/stackforms/reference/widgets/radios.md)

  * Pre-Defined values
  * Allow the use of [value mapping](/reference/stackforms/concepts/value-mapping.md)

## `integer` or `float`[​](#integer-or-float "Direct link to integer-or-float")

* [number](/reference/stackforms/reference/widgets/number.md)

  * Allow arbitrary values

* [text\_area](/reference/stackforms/reference/widgets/text_area.md)

  * Allow arbitrary values

* [dropdown](/reference/stackforms/reference/widgets/dropdown.md)

  * Pre-Defined values

* [slider\_range](/reference/stackforms/reference/widgets/slider_range.md)

  * Pre-Defined values

* [slider\_list](/reference/stackforms/reference/widgets/slider_list.md)

  * Pre-Defined values

* [cy\_inventory\_resource](/reference/stackforms/reference/widgets/cy_inventory_resource.md)

  * Available resources in [Cycloid asset inventory](/reference/inventory/.md)

## `boolean`[​](#boolean "Direct link to boolean")

* [switch](/reference/stackforms/reference/widgets/switch.md)

* [radios](/reference/stackforms/reference/widgets/radios.md)

* [text\_area](/reference/stackforms/reference/widgets/text_area.md)

  * Allow arbitrary values

## `array`[​](#array "Direct link to array")

* [text\_area](/reference/stackforms/reference/widgets/text_area.md)

  * Allow arbitrary values

* [dropdown](/reference/stackforms/reference/widgets/dropdown.md)

  * Pre-defined values
  * Multiple items using the `widget_option` > `multiselect: true`
  * Allow the use of [value mapping](/reference/stackforms/concepts/value-mapping.md)

* [auto\_complete](/reference/stackforms/reference/widgets/dropdown.md)

  * Allow arbitrary values
  * Multiple items using the `widget_option` > `multiselect: true`

* [cy\_inventory\_resource](/reference/stackforms/reference/widgets/cy_inventory_resource.md)

  * Available resources in [Cycloid asset inventory](/reference/inventory/.md)

## `map`[​](#map "Direct link to map")

* [text\_area](/reference/stackforms/reference/widgets/text_area.md)
  * Allow arbitrary values


---

# Widgets

| Widget                                                                                          | Render                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [**simple\_text**](/reference/stackforms/reference/widgets/simple_text.md)                      | ![st](data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAN0AAABOCAIAAAArVISgAAAAA3NCSVQICAjb4U/gAAAAGXRFWHRTb2Z0d2FyZQBnbm9tZS1zY3JlZW5zaG907wO/PgAAEFxJREFUeJztnHtUFdXbx/feM4fhogGih0uHhSloLOWi4KXwhV8/TPR9Ka/lrayUwguv5rI0Xeali5eMZYrrFVtqb2a6VmFimOGNAjVJK8BEEvnJ7YhcfqDC4RzOmZm93z82jBNQdkgPg+/+/MEaZvbs2TPPd579PHvvOdBmswEGQ2Og7m4Ag9EJTJcMLcJ0ydAiTJcMLcJ0ydAiTJcMLcJ0ydAiTJcMLcJ0ydAiTJcMLcJ0ydAiTJcMLcJ0ydAiTJcMLcJ0ydAiTJcMLcJ0ydAiTJcMLcJ37TRCCAAAQEi3MP2X8bCAIISg1b4AAPqfI+mKLgkhtKEyxghCQacDDm8348FCiE0UMcYIIaiyuMOwW5e0iYQQTIizIAAs51VX59XU1ljMMiZMnz0aQgCHoN7FJVyvj/D2BhzXYrUiCKnFHSlNaNf3kLRxtNcWnJwy//Wvvb9eRgg93sezj4srQhDQ/pyps8fRZjiCSX2L5Wp9gyjLrwwd8l9BQVabDQCAHCtNO3SpeEoCgKDTrTt77mJNzbIRkf8MCHigTWR0C9mVlckXLg718toQHW2VRAiAI72m3f4SE+IsOK3JPlNpbt4dF8chhDEmbe8b4yEAAgABQAgRQhJPnPB0Ejb/I6bFZqMduoPaYJe/lAlxcXL66urVTwqvHJkyGQIgY8yh1sEm+j6B7kjfGH8TxXCkbWhFJgRBiCCcfDh9elDQjKFDLC1WDjlImnaMXxIAeAgtNtvey4Ubov8DQSgTwnMcgK0AAKADXynGfaS9BSHkEaKJxObo6H1FRaaWFp5DDusV7dElITqd7qzR6O3mGtKvn4QxR18vNnj58EEIIYSDUMJ4kFcf/0ce+b6iQqfjiaNsbZ8uCYQXq2sifX2pHJU37C+e3lpJ20bHQ7Isdzz615sHAMAY/51K7ll/x/bbu79HcNeyhBBCRvn5/lRTQwh02F3YMX5Js/Gq5uYQb29gT3amxC6KYgAAHMcp28pT4DhOvccu6CkIoXZ7Om2POpBSbkRpJ8aY6gkhRMN/ZT/GmJ6lvpByXxBCpTwAQJIkpbC6HntvrVtQ29fQu/ePN6ogIA4boLbDX1LtiBjrOAQhJH/tEdN7o0blOI5vQ+1rqcGam5tzcnIaGxtBl7wLVcyNGzfOnz9Pt+9ZSbsCsG0AGSFEm0rFp7QfIaS0XzlECFHui+M4daCmLowxVuq399a6C8XKOoREjB35Stk933PXr3R2tGPv3DrkSQhC6Jdfftm7d29jY2NkZGRCQoKLiws1tizLHMcZjcZZs2ZlZGSEhYXJsszzvLoqqgNaldrAyh5ZlhFCmZmZ27dvv3DhgiAIyqF27VE3CQBA26DUhhDKz88vLCysra0dOnTo008/TVWOELp+/frOnTurq6sHDRq0cOFCLy8veu7p06fT0tLMZnNMTMycOXOodzSbzampqfn5+R4eHvPmzQsLC1Okae8z70ZoWx0/D9m19UR/2ES1t6DmgRBKkgQh/P777ydNmuTu7v7UU08dOHBg0aJF9BTlnhFCzs7OdEOn06nTQ6QaiqJ1KudS30YdEgCA4zhBEBS3pxRW/yvLMq32+eefz8nJoS+Gus6TJ09+9dVXH3744fHjxwEA9GhxcfGECROamprGjRuXm5s7Y8aM5uZmCOH+/fvnz58fGBgYFRW1adOmtWvXIoRaWlpmzZr19ddfx8bGCoIwZcqUS5cuKRFCl555t9Ij1m38SSPVIVRBQQHGOCQkRKfTEUKOHj367LPPvv/++wCAYcOGxcfHG41Gf39/RRPUh7m6ulZWVt66dSs0NJTKq7m5+c6dO48++igtU11d7ebm9sgjj1BtlZWV1dXVBQcH9+rVq12qIYpieXm5wWAQBAEhVFZWVl9fP2TIEGdnZ6vVWlxcfPHixby8vMDAQG9vb3oKdZxvvvkmAGDmzJmKk4YQnjp1Kjg4ODU1FQAQHx8fGhqan58fFRX13nvvLVmyJCkpCQDQt2/fFStWrF69ury83Gg0pqenGwwGAMClS5cOHjwYGhraI0XZHfPKXVzn9kdQE968eXPBggV1dXU0xkpNTR08ePC6desEQaDFaAJBCKHpM2hLg5ycnDZu3Hjz5k2j0fj444/v2rXLy8srLS1t27ZteXl5tP5Zs2ZNnTo1KSnJarWuWLHi7Nmznp6eDQ0NmzdvHjt2LE1BqNYTExNv3Lhx6NAhnU63fv36jIwMDw+P5ubm3bt3+/r6rly5UqfTffrppyaTaeXKlaIoKs6Ydrg2m00t1ldeeSUhIUG5UyUB2rVrV0hIiNVqpcElQshmswUGBmZnZ7u5udEykiSp8yTGPbnPusQY8zyfkpJSVVV14cIFURSnTJmyY8eOHTt2UCN98803N2/eTE9PX7Zsmb+/P4TQycmJnosQampq8vHx2bp1a3Nz8/jx45OTkzdu3ChJEpUIdZ82m00URQBASkrKiRMnjh07FhAQsHXr1rlz55aUlFDf7OrqeuDAgczMzOzs7F69en3yySdffvllVlaWr6/vqlWrli1bdvLkyX379kVHRy9fvnzatGkIIaUZVHDqcIpe18XFBQDw3XffXb9+PSsra/r06aNHj8YYx8TEAAAkSeJ5/uOPPx43bpy7u7ssy25ubr/99ltubm5JSYmLi8vChQtpLNGz4svu4n7qUokU9Xp9Q0NDVlbWqFGjMjIy7ty5o4xN/vDDDwUFBaWlpTNnzoQQZmZmnjt3DmMcGRkZERHB8/zcuXM9PT09PT0XLVq0a9euDRs2KLEmhQaUAIAjR47MmTOnf//+GOPFixd7e3vTLMRqtX7xxRebN2/euXNnUFAQISQtLS0iIqK2tra8vDwwMHD//v1VVVW076b58vnz548dO4YQ8vf3nzdvHvj9xBXVE3Wo+fn5VJovvfQS9aOiKFJPv3bt2tra2oMHD9JOAGNsNBqPHj1aWVk5YMAANzc3Jcxg0rwn91OXtBfDGL/++us8z69bt85ms0VFRa1duxYAQPNrGl/m5ORMnz79iSeegBCazWYAALU6hLCpqYl28QaDoampqZ0+KFSXFotFr9fLsizLspOT0+zZs2mxpqam1NRUi8UycuRIjLEkSaIoXrly5e2335YkiRASGRlJQwjQNvQoy3JLSwvtgju9L0KITqcDACxdunTp0qXl5eVRUVGhoaFxcXGiKAqCkJqa+tlnn3377bceHh60PQCAsWPHjh07lhASGxv77rvvJicn0w6d6fKePBB/WVZWlpSUlJSUlJ+fn5SUNH/+/AMHDqSlpT322GMRERGyLI8YMaJv375XrlyJj4+Pi4ujpxcXF0MIe/fuTUMxk8nE8zx1RYo66RghDUmdnZ3r6+uV8fmff/45PDxclmW9Xn/69OkZM2YkJCRkZGTQSp555pn169fTASl6OZPJREcAIIRjxowZM2YM3a8Ejgo0ODl16hSEMDY2VpKkgICAoKCgoqKicePGCYJw6NChTZs2HT58ePDgwXSYtqSk5Mcff5w9e7YoijqdLiYm5qefflJGphj35D4/JppwvPXWW88995zZbA4PD4+MjKyoqAAAZGZmvvrqq42NjRzHpaWlNTU1hYeHY4xtNpvNZqPmtFgse/fuNZlMt2/f3rlzZ3R0NIRw4MCB9fX1ubm5kiRlZGRcvXqVut74+Ph9+/ZVVVXxPL9nz545c+bQflySJIxxSkpKYWFhcnIyQmjy5Mmff/55SUkJx3GlpaXZ2dm0ByeElJeXAwBEUZQkSZIk2v52eT1NgwoKCl588cWKigqe58+cOXP16tWRI0dCCLOyst54443t27eHhoY2NjaaTCZJksxm82uvvXbkyBGdTldXV5eenj569Gglo7q/z/yhpIvf93S6nz5xjPGaNWsWLFgQGxvr5ORkNps/+ugjjPHGjRsXLlwYFxfn5eVlNBq3bNliMBhkWaaZCo0L+/fvb7FYJk+e3NDQ4OHhsWbNGoxxRETECy+88PLLL/v5+Q0fPjw4OJjmPUuWLKmoqJg4caJer6+trd2yZYtOp7PZbDzPW61WvV6fkpKSmJgYHR2dmJh4/fr1adOmBQQEGI3GiRMnRkdHC4IwderUd955x2QyrVq1Shk8J6p5f7rBcRwNYUtLSydNmmQwGMrKypYvX/7kk0+KovjBBx9gjFNTU5OTkzmOo7VNmjRp27Ztq1ev3r17d01NTVhY2OLFi1s/l+mBunT88JYd6y8ljF0EYf7xExODAicMGKBeeUlRUmY6ll5QUGCz2UJDQ93c3KhJAAC//vrr7du3Q0JCPDw81FNzEEKr1Xrr1i0fH5/i4uLGxsbw8HCe55UyhYWFNptt2LBhDQ0NCCEPDw960WvXrlHD9+7dmxBiMpkaGxv9/Pyo1isrKwVB0Ov1AIDS0tIbN27079/fYDAoHjEvL8/d3X3gwIGtj0M1S15TU6PT6fr06aMelL127VpVVdXgwYN9fHzo/pqaGqvVarValdkjb29vGo3U1dUVFRX169cvODi43fP5+5ZzDNTKWeXln18p2jNhvMVq5R0Sitity8TM45MHDRo/4DEJY74zXYK2mT1lv3qiTzGJEuq1s5P6344ndjqv2K7CjkfVs44dr9jpno60q4ROe/7JWer2ENWULACOnGf+u1Arf1dR8dnlwr3/OcFhurRnPREAhBBnjrPKEiGk4+eb6ueuJLzUeEpHQHNtCKGSr0DVch66Qct0PBG0LepRJ+kdKySqCXQlnlOqVQ4pp0PVIiD4+1VF7QqrK1HP17d7ULBtWlV9RdADR4gUK1tlWeC4Tm71gWGHLiEhAEL/3r3L2pb8QFU01lpGta32Xp0WULbbxXOdGq9dYfVZ7cqoC/xR2zo2smP96kn5P6nkT6TWs1TYjlZngTGAsPT2Hf9evehb65ir27PODUJIyBN+vheqbt51JD1q4RbjL3LXshBCCHOrqkb7+UIH+nv71l/aRHGUn59FFHMqKzmEZIyhqu9jPBy0xh4AyITwCF2oqrrd0hJlMNhE0WH+3z5/iQnhOO71iGHrzp27Y7XyHCf+/qOFTuMthvZRDKf8FWWZR8gsiqvOnPnv8HCB52Vt/q4BuPv9uJD68y/flJXuGT9e7+YGAMCE9Mx1hYz2QADo57kAgHqLJSEz8x8Gw5IRI5QfhHFQM7rwexsyIS6CsCe/YH9R0YtDh0wdNMi9bQEb4+GgyWo9fO3a/14ufH5Q0Pzhwy1WK6caaXZAA7ry+0SKNAtra/8nP7/K1Ozj5tZLcFLWj/bkNPT/KervX0w2sdpk8nF1nR8eFubj0y0/nWWfLkG733PT6QBC1Y2Nl//97zqLBROifBDyINrKeJC0Gg5B2NfZZUhfLz93d4Bxiyj2gN9zo7QOHwBAv2YVOA7y93l9MaN7IbJslSQIIYKQ5kEOHovtii5Bh4l8lvQ8TNDU53d7esR3Z6BDQzkWUTLuK2yZKkOLMF0ytAjTJUOLMF0ytAjTJUOLMF0ytAjTJUOLMF0ytAjTJUOLMF0ytAjTJUOLMF0ytAjTJUOLMF0ytAjTJUOLMF0ytAjTJUOLMF0ytAjTJUOLMF0ytAjTJUOLMF0ytAjTJUOL/B9hrKDOSanbsAAAAABJRU5ErkJggg==)<br />Simple field dedicated to text                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| [**number**](/reference/stackforms/reference/widgets/number.md)                                 | ![n](data:image/png;base64,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)<br />Simple field dedicated to numbers                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| [**text\_area**](/reference/stackforms/reference/widgets/text_area.md)                          |  ![ta](data:image/png;base64,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)<br />Multi-line text field                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| [**dropdown**](/reference/stackforms/reference/widgets/dropdown.md)                             |  ![dd](data:image/png;base64,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)<br />Menus display a list of options                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| [**auto\_complete**](/reference/stackforms/reference/widgets/auto_complete.md)                  | ![ac](data:image/png;base64,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)<br />Provides suggestions while you type into the field                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| [**radios**](/reference/stackforms/reference/widgets/radios.md)                                 |  ![r](data:image/png;base64,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)<br />Graphical control element that allows the user to choose only one of a exclusive options |
| [**switch**](/reference/stackforms/reference/widgets/switch.md)                                 |  ![ta](data:image/png;base64,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)<br />Choosing between 2 positions `on/off`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| [**cy\_cred**](/reference/stackforms/reference/widgets/cy_cred.md)                              | ![cred](/assets/images/credentials-5665fc04264847f55220d6545406739f.png) <br />Expose cycloid credentials available                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| [**cy\_inventory\_resource**](/reference/stackforms/reference/widgets/cy_inventory_resource.md) | ![inventory](data:image/png;base64,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)<br />Select a resource attribute from the inventory and link the value to this asset                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| [**slider\_range**](/reference/stackforms/reference/widgets/slider_range.md)                    |  ![sr](data:image/png;base64,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)<br />Select option by dragging a slider along a range                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| [**slider\_list**](/reference/stackforms/reference/widgets/slider_list.md)                      |  ![sl](data:image/png;base64,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)<br />Select option by dragging a slider along list of options                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| [**cy\_scs**](/reference/stackforms/reference/widgets/cy_scs.md)                                | ![scs](/assets/images/scs-83a234b059fb33df1b242ae62fe2afff.png)<br />Expose cycloid catalog repositories available                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| [**cy\_crs**](/reference/stackforms/reference/widgets/cy_crs.md)                                | ![crs](data:image/png;base64,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+OCDu3btkiTp8OHDNptt3LhxBw4cCAQCixcvDgQCH374ISGkoKBg7ty569aty87OjoqK+uKLL7Zu3Wq32+Pj471e7/Tp010u14svvrh06dJTp07V1tbSNL179+6f/OQnLMuePHnyq6++OnPmTFxc3KJFiywWy2uvvTZhwoSbb75ZluX169cPHjx43LhxNE2XlpYePXq0vr5+wIABc+bMMR5BaJoWRfHf//53U1MTISQ2Nra4uNhutx87dmz79u2CIASDwR//+Mf5+fmNjY2vvvpqZmbmuXPnmpubJ0+e3N7efuLEic7OzuLi4tzc3FOnTm3fvv2+++5zOp3/+c9/Dh8+HBcXRwihaRo81g0bNlRWVtI0bbFYFixYEBcXt2vXrra2NqvVWllZabVaFy1aFBMTEwgE1q9f39DQ4HK5GIax2+2zZ89+9913W1tbLRZLa2srTdMrV67UNG3jxo3QIZGRkfPmzbNYLIQQURQrKipmzZql67rX6920aVNHR4csy1lZWbNmzRIE4dChQ3v37uV5XpKk2267LTs72/DBd+7cKUlSeXm5w+EYP358VVXVO++8QwiRJGn69OmDBw9ua2vbtGmTx+NRVTUlJWXevHn79u1rb2//8ssvo6OjJ02aBI810KtvvfVWfX09tIJhmLvuuqukpITjuDFjxuzbt4+iqG3bts2ePTshIcF4bkMQ5FrSfVweQhAVFRX79u1buHDhsmXLGIY5f/48RDZ8Ph9FUbfffntYWFhhYeG4ceNkWT569Choweuvv+71epubm9evX2+322NiYqqrq1VVLSkpGTly5KOPPpqTk1NdXQ366Pf7g8Hg2LFjb7rppoyMjOLiYkIITL0WFxc/8sgjjY2NR44c4Xne5/MZMRm/3w9RBVmWbTbbokWLli1bduzYsbKyMgjuE0I4jtu5c2ddXd0vfvGLFStWNDQ0lJaWiqK4cePGMWPGPPzww5MmTdq8ebPX6+V5vqmpKS4u7sEHHxw7duy6devsdvvKlSuzs7N37NihKIrb7Z4xY4bdbq+srNy7d++dd955//33u1wuWZbBtW9qalq+fPmTTz6pquqHH35IUVRnZ2djY+O0adNWrVql6/r+/fsZhvnwww/r6+tXrlw5f/58r9fb0dEhCMLcuXOXLVu2YMECSZJuvvlmi8Wye/fus2fPLl++/KGHHmpvb3/v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)<br />Expose cycloid config repositories available                                                                                                                                                    |
| [**cy\_branch**](/reference/stackforms/reference/widgets/cy_branch.md)                          | ![branch](/assets/images/branches-59f86e6f2c445e3a8728acfb0a6068ea.png)<br />Expose branches available from `cy_scs` or `cy_crs`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |

## Define pipeline variables[​](#define-pipeline-variables "Direct link to Define pipeline variables")

## Terraform variables[​](#terraform-variables "Direct link to Terraform variables")

#### Define the widget variable in your [.forms.yml file](/reference/stackforms/concepts/forms-file.md)[​](#define-the-widget-variable-in-your-formsyml-file "Direct link to define-the-widget-variable-in-your-formsyml-file")

.forms.yml

```
use_cases:
- name: myusecase
  sections:
  - name: mysection
    groups:
    - name: mygroup
      # Here we use the terraform technology
      technologies: [terraform]
      vars:
        - name: "Terraform variable"
          description: "Example of terraform variable."
          key: my_terraform_variable
          widget: simple_text
          type: string
          default: "mydefaultvalue"
```

#### Define your variable in your terraform module[​](#define-your-variable-in-your-terraform-module "Direct link to Define your variable in your terraform module")

terraform/your-module/variables.tf

```
variable "my_terraform_variable" {
    type = string
}
```

#### Don't forget to create your main.tf.sample[​](#dont-forget-to-create-your-maintfsample "Direct link to Don't forget to create your main.tf.sample")

main.tf.sample

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

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

  other_module_variable = ""

  # The terraform variable will be injected by StackForms as a module argument here
  # like that :
  my_terraform_variable = "mydefaultvalue"
}
```

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

## Ansible variables[​](#ansible-variables "Direct link to Ansible variables")

### Details[​](#details "Direct link to Details")

StackForms will inject ansible variables using the `--ansible-extra-var` command line argument. So they will always win [according to ansible variable precedence](https://docs.ansible.com/ansible/2.9/user_guide/playbooks_variables.html#variable-precedence-where-should-i-put-a-variable "Ansible documentation: variable precedence.").

### Example[​](#example "Direct link to Example")

#### Define the widget variable in your [.forms.yml file](/reference/stackforms/concepts/forms-file.md)[​](#define-the-widget-variable-in-your-formsyml-file-1 "Direct link to define-the-widget-variable-in-your-formsyml-file-1")

.forms.yml

```
use_cases:
- name: myusecase
  sections:
  - name: mysection
    groups:
    - name: mygroup
      # Don't forget to use the ansible technology
      technologies: [ansible]
      vars:
        - name: "Ansible variable"
          description: "Example of ansible variable."
          key: my_ansible_variable
          widget: simple_text
          type: string
          default: "mydefaultvalue"
```

Keep in mind your variable name is defined by the `key` field (`my_ansible_variable`)

#### Use your variable in ansible[​](#use-your-variable-in-ansible "Direct link to Use your variable in ansible")

ansible/playbook.yml

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

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


---

# auto\_complete

```
widget: auto_complete
```

The autocomplete widget is similar to a dropdown but allows users to provide their own values in addition to selecting from predefined options.

* Rendering
* Code

![widget](/assets/images/auto_complete-d024ad60de4b5da46611b9469a2fc5a6.png)

.forms.yml

```
use_cases:
- name: "Demo usecase"
  sections:
  - name: "My section"
    groups:
    - name: "My group"
      technologies: ["pipeline"]
      vars:
        - name: "myvariable"
          widget: auto_complete
          key: myvariable
          type: "string"
          default: foo
          values:
            - foo
            - bar
```

## Attributes constraints[​](#attributes-constraints "Direct link to Attributes constraints")

| Attribute name                                                              | constraints      |
| --------------------------------------------------------------------------- | ---------------- |
| [type](/reference/stackforms/concepts/variables.md#type)                    | `string`         |
| [values](/reference/stackforms/concepts/variables.md#values-and-values_ref) | At least 1 value |


---

# cy\_branch

```
widget: cy_branch
```

This widget must be used with either `cy_scs` or `cy_crs`. Its purpose is to expose available Git branches in Catalog or Config Git repositories.

| Attribute  | Type     | Required | Description                                        |
| ---------- | -------- | -------- | -------------------------------------------------- |
| **source** | *string* | yes      | Should contain the `key` of a `cy_scs` or `cy_crs` |

The `cy_branch` widget is unique in that it utilizes the `source` attribute to determine which repository to query. Therefore, the **source** attribute must reference a valid **key** associated with either a `cy_scs` or `cy_crs` \[variable]\[stackforms-variable]. Failure to adhere to this requirement will result in an error.

* Rendering
* Code

![widget](/assets/images/cy_branch-9cb4eb6a19b798b62ed9a7a2fb5b226a.png)

.forms.yml

```
use_cases:
- name: "Demo usecase"
  sections:
  - name: "My section"
    groups:
    - name: "My group"
      technologies: ["pipeline"]
      vars:
        - name: "Repository"
          widget: cy_crs # or cy_scs
          key: myrepo
          type: "string"

        - name: "branch"
          widget: cy_branch
          key: myvariable
          source: myrepo
          type: "string"
          default: "config"
```

## Attributes constraints[​](#attributes-constraints "Direct link to Attributes constraints")

| Attribute name                                                              | constraints    |
| --------------------------------------------------------------------------- | -------------- |
| [type](/reference/stackforms/concepts/variables.md#type)                    | `string`       |
| [values](/reference/stackforms/concepts/variables.md#values-and-values_ref) | Not compatible |


---

# cy\_cred

```
widget: cy_cred
```

The credential widget assists users in selecting Cycloid credentials. This widget outputs a credential path, which combines the canonical name with a specific field.

It offers specific configurations, such as filtering specific credential types. Additionally, it may return values differently depending on the technology used.

* Rendering
* Code

![widget](/assets/images/cy_cred-02f6ecd411e8112a3ad594fed149dfea.png)

.forms.yml

```
use_cases:
- name: "Demo usecase"
  sections:
  - name: "My section"
    groups:
    - name: "My group"
      technologies: ["pipeline"]
      vars:
        - name: "myvariable"
          widget: cy_cred
          key: myvariable
          type: "string"
```

## Attributes constraints[​](#attributes-constraints "Direct link to Attributes constraints")

| Attribute name                                                              | constraints    |
| --------------------------------------------------------------------------- | -------------- |
| [type](/reference/stackforms/concepts/variables.md#type)                    | `string`       |
| [values](/reference/stackforms/concepts/variables.md#values-and-values_ref) | Not compatible |

Due to the internal workings of Pipelines, the `default` attribute has a different syntax depending on the technology used. The `default` should contain the path of a credential. For a pipeline technology, it should also be surrounded by `((mycred))`. Please refer to the section on using [Cycloid credentials in a pipeline](/reference/ci-cd-pipelines/concepts/tools-integration/.md) for more information on this matter.

## Widget configuration[​](#widget-configuration "Direct link to Widget configuration")

Widget specific configuration are stored under `widget_config` attribute.

.forms.yml

```
      vars:
        - name: "myvariable"
          widget: cy_cred
          widget_config:
            attribute: <value>
```

For this widget *widget\_config* supports the following configuration

| Attribute           | Type      | Required | Description                                                                                                                                                                                    |
| ------------------- | --------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **cred\_types**     | *array*   | no       | Filters the types of credentials to display. See [credential types](/reference/credentials/concepts.md). Default displays all types.                                                           |
| **display\_keys**   | *boolean* | no       | Asks the user to select a specific key for a selected credential. Default is `true`.                                                                                                           |
| **format**          | *string*  | no       | Credential format, one of: 'path', 'uri'. Defaults to path. Only credentials in URI format can be shared between technologies.                                                                 |
| **uri\_parameters** | *map*     | no       | Optional query parameters that should be encoded and added to the resulting credential URI by the client. Used to specify for example output format (e.g. json). Applies only if format='uri'. |

### `cred_types`[​](#cred_types "Direct link to cred_types")

In this example we filter only credentials of type **ssh**:

* Rendering
* Code

![widget](/assets/images/cy_cred_cred_types-91c7d8f6be77e7fcb8ffd63f76ee9563.png)

.forms.yml

```
...
      vars:
        - name: "myvariable"
          widget: cy_cred
          key: myvariable
          type: "string"
          widget_config:
            cred_types: ["ssh"]
```

### `display_keys`[​](#display_keys "Direct link to display_keys")

This option modifies the behavior of the `cy_cred` widget value. Instead of returning both the credential path and the name of a key, it will return only the path.

Depending on the technology and how your stack handles credentials, there are some use cases where you would prefer to receive only the path of a credential instead of a specific key. This could be useful, for example, in a pipeline where using a path will return the entire content of a credential. Refer to the [pipeline and credential sections](/reference/ci-cd-pipelines/concepts/pipeline.md#variable-lookup) for more examples.

* Rendering
* Code

![widget](/assets/images/cy_cred_display_keys-51c4ab0a55845602a632846b1317b63c.png)

.forms.yml

```
...
      vars:
        - name: "With cred keys"
          widget: cy_cred
          key: myvariable
          type: "string"
          widget_config:
            display_keys: true

        - name: "Without cred keys"
          widget: cy_cred
          key: myvariable2
          type: "string"
          widget_config:
            display_keys: false
```

### `format`[​](#format "Direct link to format")

We support two credential representations:

* `path`: the default representation, inject the credential path with a format depending on the technology.
* `uri`: output a [Cycloid URI reference](/reference/stackforms/examples/using-the-cli.md) to the credential.

### `uri_parameters`[​](#uri_parameters "Direct link to uri_parameters")

This attribute will only be used with the `format: "uri"`.

`uri_parameters` are query parameters added to the Cycloid URI format to help with formatting.

You can list all the supported query parameters by using the cli command `cy uri interpolate --help`.

Here is a summary of main options.

```
uri_parameters:
  # Specify the output format, json or yaml
  output: "json"

  # Manage the indentation size of any indented formats (json, yaml)
  indent_size: "2"

  # indent the final output with x spaces from the left
  indent: "2"
  # same as indent with a preceding newline
  nindent: "2"
  # Encode the output in base64
  base64: "true"
```

Those URLs can be interpolated by the [Cycloid CLI](/reference/cli/.md) at runtime in your pipeline to inject values in your files.

**Example:**

* StackForms
* Template
* File in config repository

.forms.yml

```
use_cases:
- name: "default"
  sections:
  - name: "section1"
    groups:
    - name: "group1"
      technologies: [custom]
      vars:
      - name: "SSH KEY"
        key: ssh_key
        widget: cy_cred
        type: string
        widget_config:
          cred_types: [ssh]
          format: uri
          display_keys: true
          uri_parameters:
            base64: "true"
```

template.yaml.tmpl

```
---
apiVersion: v1
kind: Secret
metadata:
  name: my-secret
data:
  # The url represent what will be injected by stackforms
  # This fetches an ssh_key and encode it in base64
  ssh_key: ($ .ssh_key $)
```

template.yaml

```
---
apiVersion: v1
kind: Secret
metadata:
  name: my-secret
data:
  # The url represent what will be injected by stackforms
  # This fetches an ssh_key and encode it in base64
  ssh_key: cy://organizations/your_org/credentials/test-ssh?key=.raw.ssh_key&base64
```

You can now use the CLI to interpolate the URI with

```
$ cy uri interpolate -f template.yaml
```

template.yaml

```
---
apiVersion: v1
kind: Secret
metadata:
  name: my-secret
data:
  ssh_key: LS0tLS1CRUdJTiBPUEVOU1NIIFBSSVZBVEUgS0VZLS0tLS0KYjNCbGJuTnphQzFyWlhrdGRqRUFBQUFBQkc1dmJtVUFBQUFFYm05dVpRQUFBQUFBQUFBQkFBQUFNd0FBQUF0emMyZ3RaVwpReU5UVXhPUUFBQUNBaW9RaGJDTnVSYzZmWmhqa3JyRUJxMEphUFAzS05iR0gyVEszMGt2aE9LUUFBQUlqbmppNTQ1NDR1CmVBQUFBQXR6YzJndFpXUXlOVFV4T1FBQUFDQWlvUWhiQ051UmM2ZlpoamtyckVCcTBKYVBQM0tOYkdIMlRLMzBrdmhPS1EKQUFBRURRcUlXTVNvWURLb0hYdG1Xdy9mbTE4YzZBVWhRcEhkV3AvelhMSWVwbmdTS2hDRnNJMjVGenA5bUdPU3VzUUdyUQpsbzgvY28xc1lmWk1yZlNTK0U0cEFBQUFBQUVDQXdRRgotLS0tLUVORCBPUEVOU1NIIFBSSVZBVEUgS0VZLS0tLS0=
```

What if I need the credential at multiple places with different formats ?

You can just define a `cy_cred` without the formatting parameters and add them in the templating.

note

Note that when `display_keys` is `true`, the basic url will include the `key` parameter like this:

```
cy://organizations/my-org/credentials/my-cred?key=.raw.<key>
```

whereas if `display_keys` is `false` you will get:

```
cy://organizations/my-org/credentials/my-cred
```

So in case you want to do add parameters, you will have to begin with `?` when `display_keys` is `false` and `&` when it's `true`.

So to use this in action, here is an example of the same credential used in two different template file.

* Forms
* Template
* Before interpolation
* After interpolation

.forms.yml

```
use_cases:
- name: "default"
  sections:
  - name: "section1"
    groups:
    - name: "group1"
      technologies: [custom]
      vars:
      - name: "SSH KEY"
        key: ssh_key
        widget: cy_cred
        type: string
        widget_config:
          cred_types: [ssh]
          format: uri
          display_keys: false
```

secret.yaml

```
...
metadata:
  # Inject the ssh key canonical with the cy reference
  name: ssh-key-($ .ssh_key $)?key=.canonical
data:
  # Just put the base64 encoded ssh key
  my_key: ($ .ssh_key $)?key=.raw.ssh_key&base64
...
```

secret.yaml

```
...
metadata:
  name: ssh-key-cy://organizations/my-org/credentials/my-ssh-key?key=.canonical
data:
  my_key: cy://organizations/my-org/credentials/my-ssh-key?key=.raw.ssh_key&base64
```

secret.yaml

```
...
metadata:
  name: ssh-key-my-canonical
data:
  my_key: azjidhalizdhainclakzjhndlaqIUZjdhLZJHDJKAHZLDJhaizdhncajkzhcljzhdlajzhnd
```

### Using cy\_cred with External Tools like Terraform and Ansible[​](#using-cy_cred-with-external-tools-like-terraform-and-ansible "Direct link to Using cy_cred with External Tools like Terraform and Ansible")

Please refer to the section dedicated to [forwarding pipeline variables to technologies](/reference/ci-cd-pipelines/concepts/tools-integration/.md) for more information.


---

# cy\_crs

```
widget: cy_crs
```

Similar to the `cy_srs` widget, `cy_crs` exposes available Cycloid config repositories. When selected, it returns the Git URL of the config repository.

**Note**: The `default` attribute should be the URL of the Git repository.

* Rendering
* Code

![widget](/assets/images/cy_crs-8d29880506ce8a5b03358169d7c5c466.png)

.forms.yml

```
use_cases:
- name: "Demo usecase"
  sections:
  - name: "My section"
    groups:
    - name: "My group"
      technologies: ["pipeline"]
      vars:
        - name: "widget"
          widget: cy_crs
          key: myvariable
          type: "string"
          default: "git@....git"
```

## Attributes constraints[​](#attributes-constraints "Direct link to Attributes constraints")

| Attribute name                                                              | constraints    |
| --------------------------------------------------------------------------- | -------------- |
| [type](/reference/stackforms/concepts/variables.md#type)                    | `string`       |
| [values](/reference/stackforms/concepts/variables.md#values-and-values_ref) | Not compatible |


---

# cy\_inventory\_resource

```
widget: cy_inventory_resource
```

The inventory widget integrates with Cycloid's [Asset inventory feature](/reference/inventory/.md). It enables users to create a resource selector within a form, automatically populating resources from their Inventory based on predefined filtering criteria in the form's YAML syntax. This streamlines the form submission process by simplifying resource selection.

* Rendering
* Code

![widget](/assets/images/cy_inventory_resource-13dc08e5a577846bacbd05526b4c59d4.png)

.forms.yml

```
use_cases:
- name: "Demo usecase"
  sections:
  - name: "My section"
    groups:
    - name: "My group"
      technologies: ["pipeline"]
      vars:
        - name: "myvariable"
          key: myvariable
          type: "string"
          widget: cy_inventory_resource
          widget_config:
            attribute: id
```

Config attribute is required

See the following section about `widget_config` attribute.

## Attributes constraints[​](#attributes-constraints "Direct link to Attributes constraints")

| Attribute name                                                              | constraints                                                                                                                                                                                                                                                                                                                                                      |
| --------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [type](/reference/stackforms/concepts/variables.md#type)                    | `string`, `integer`, `array`                                                                                                                                                                                                                                                                                                                                     |
| [values](/reference/stackforms/concepts/variables.md#values-and-values_ref) | Does not take any values                                                                                                                                                                                                                                                                                                                                         |
| [default](/reference/stackforms/concepts/variables.md#default)              | If no resources are selected, the default value will be used. If no default values are provided, for Terraform technology, the variable will not be written. For pipeline technology, a zero value policy will be applied. This means that a variable will be provided with a default null value of the specified type.. Eg array `[]`, string `""`, integer `0` |

Note: The `array` type allows users to select multiple resources, resulting in an array output. A typical use case is selecting multiple subnet IDs to generate a list of subnets.

## Specific configuration[​](#specific-configuration "Direct link to Specific configuration")

Widget specific configuration are stored under `widget_config` attribute.

.forms.yml

```
vars:
- name: "myvariable"
  widget: cy_inventory_resource
  widget_config:
     ...
```

For this widget *widget\_config* supports the following configuration

| Attribute     | Type     |  Required | Description                                                  |
| ------------- | -------- | --------- | ------------------------------------------------------------ |
| **attribute** | *string* | yes       | Name of the attribute you will get from this resource        |
| **filters**   | *map*    | no        | Define filters based on your criteria for resource selection |

### Attribute `attribute`[​](#attribute-attribute "Direct link to attribute-attribute")

.forms.yml

```
...
          type: string
          widget_config:
            attribute: id
```

Define the attribute used for the selection (in this case `id`). The attribute must respect the `type` defined. The given attribute name is the "value" that you will get from the selected resource, and that you will expose as a variable.

### Attribute `filters`[​](#attribute-filters "Direct link to attribute-filters")

This attribute contains several criteria to filter resources displayed to the user, which may include attributes, provider, project, and more:

| Attribute       | Type     | Required | Description                                                                                                                           |
| --------------- | -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| **attributes**  | *string* | no       | Filter resources based on attribute values using a query string with the LHS syntax                                                   |
| **project**     | *string* | no       | Filter resources from a specific Cycloid project                                                                                      |
| **environment** | *string* | no       | Filter resources from a specific Cycloid environment                                                                                  |
| **component**   | *string* | no       | Filter resources from a specific Cycloid component                                                                                    |
| **type**        | *string* | no       | Comma separated list to specify the type of resources you want to select, for example, `aws_instance` or `aws_instance,aws_s3_bucket` |
| **provider**    | *string* | no       | Filter resources from a specific Terraform provider                                                                                   |
| **name**        | *string* | no       | Filter a resource based on the given name in Terraform code                                                                           |
| **module**      | *string* | no       | Filter resources based on the Terraform module they belong to                                                                         |

Here is an example using several filters:

.forms.yml

```
...
          type: string
          widget_config:
            filters:
              project: demo
              attributes: 'tags.env[eq]=dev'
              provider: aws
              type: aws_vpc
```

This example filters resources of type `aws_vpc` from the `aws` Terraform provider, which belong to a Cycloid project called `demo`, and resources should have a `tags` attribute containing `env == dev`.

Note: The filter `attributes` uses LHS syntax, meaning you can use the following conditions:

* `eq` is equal to
* `neq` not equal to
* `gt` greater than
* `lt` less than
* `rlike` SQL like regex syntax [MySQL REGEXP operator](https://dev.mysql.com/doc/refman/8.4/en/regexp.html#function_regexp-like)
* `in` if the value is in a given list. For example, `tags.env[in]=dev,staging` is *true* if `tags.env` contains `dev` OR `staging`.

For multiple filters, the `attributes` field currently supports the same syntax as the web console, meaning you can use **AND** conditions using `&` such as `condition&condition`.

For example

.forms.yml

```
    attributes: 'tags.env[eq]=dev&tags.project[eq]=foo'
    # This will filter resources with tags env == dev AND project == foo
```

### Integration with Inventory[​](#integration-with-inventory "Direct link to Integration with Inventory")

It's essential to ensure that your Inventory system recognizes the filtering parameters and retrieves the relevant resources accordingly. The Inventory should dynamically populate the resource selector based on the filter criteria defined in the form YAML.

To create filters for your YAML forms, you can easily generate them directly from the console. Simply perform your desired filtering, then click on the respective icon ![icon](data:image/png;base64,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).

![icon](/assets/images/stackforms-widget-inventory-generator-f7ca4b5daad42f91d976ae3e0bb52529.png)

This feature streamlines the process of resource selection in your forms. Users benefit from a more efficient and error-free experience as the resource selector automatically displays relevant options based on the predefined criteria.


---

# cy\_scs

```
widget: cy_scs
```

Expose Cycloid catalog repositories available. When selected, it will return the Git URL of the catalog repository.

**Note**: The `default` attribute should be the URL of the Git repository.

* Rendering
* Code

![widget](/assets/images/cy_scs-097628baa8699b094e9f7db901970361.png)

.forms.yml

```
use_cases:
- name: "Demo usecase"
  sections:
  - name: "My section"
    groups:
    - name: "My group"
      technologies: ["pipeline"]
      vars:
        - name: "widget"
          widget: cy_scs
          key: myvariable
          type: "string"
          default: "git@....git"
```

## Attributes constraints[​](#attributes-constraints "Direct link to Attributes constraints")

| Attribute name                                                              | constraints    |
| --------------------------------------------------------------------------- | -------------- |
| [type](/reference/stackforms/concepts/variables.md#type)                    | `string`       |
| [values](/reference/stackforms/concepts/variables.md#values-and-values_ref) | Not compatible |


---

# dropdown

```
widget: dropdown
```

The dropdown widget provides users with the option to choose from predefined values.

* Rendering
* Code

![widget](/assets/images/dropdown-ff4763da9ca0e9a994bcf1972ffabf66.png)

.forms.yml

```
use_cases:
- name: "Demo usecase"
  sections:
  - name: "My section"
    groups:
    - name: "My group"
      technologies: ["pipeline"]
      vars:
        - name: "myvariable"
          widget: dropdown
          key: myvariable
          type: "string"
          default: foo
          values:
            - foo
            - bar
```

## Attributes constraints[​](#attributes-constraints "Direct link to Attributes constraints")

| Attribute name                                                              | constraints                                                   |
| --------------------------------------------------------------------------- | ------------------------------------------------------------- |
| [type](/reference/stackforms/concepts/variables.md#type)                    | any but raw                                                   |
| [values](/reference/stackforms/concepts/variables.md#values-and-values_ref) | At least 1 values, if Boolean only 2 allowed (`true`,`false`) |

## Specific configuration[​](#specific-configuration "Direct link to Specific configuration")

Widget specific configuration are stored under `widget_config` attribute.

.forms.yml

```
      vars:
        - name: "myvariable"
          widget: dropdown
          widget_config:
            attribute: <value>
```

For this widget *widget\_config* supports the following configuration

| Attribute       | Type      | Required | Description                                                                                                        |
| --------------- | --------- | -------- | ------------------------------------------------------------------------------------------------------------------ |
| **multiselect** | *boolean* | no       | Allows the user to select multiple elements from the list. The output value will be an array of selected elements. |

### Attribute `multiselect`[​](#attribute-multiselect "Direct link to attribute-multiselect")

To use multiselect mode, you need to do two things: ensure that `multiselect` is enabled in the `widget_config` section, and change your widget type to array, as the output will become an array.

* Rendering
* Code

![widget](/assets/images/stackforms-multiselect-5e1186a854d872609d4166fc24d94257.gif)

.forms.yml

```
...
      vars:
        - default: [bar]
          key: two_b
          name: select several values
          type: array
          values: [foo, bar, baz]
          widget: dropdown
          widget_config:
            multiselect: true
```

**Considerations**:

* **Default values**: The `default` value must be specified within an array to ensure proper functionality.


---

# number

```
widget: number
```

* Rendering
* Code

![widget](/assets/images/number-46ed7d09dfc84fe37927b6d6cc1fc431.png)

.forms.yml

```
use_cases:
- name: "Demo usecase"
  sections:
  - name: "My section"
    groups:
    - name: "My group"
      technologies: ["pipeline"]
      vars:
        - name: "Simple number widget"
          widget: number
          key: myvariable
          type: "integer"
          default: 10
```

## Attributes constraints[​](#attributes-constraints "Direct link to Attributes constraints")

| Attribute name                                                              | constraints        |
| --------------------------------------------------------------------------- | ------------------ |
| [type](/reference/stackforms/concepts/variables.md#type)                    | `integer`, `float` |
| [values](/reference/stackforms/concepts/variables.md#values-and-values_ref) | Not compatible     |


---

# radios

```
widget: radios
```

* Rendering
* Code

![widget](/assets/images/radios-21125eefab0a5a56e70a974b4562110e.png)

.forms.yml

```
use_cases:
- name: "Demo usecase"
  sections:
  - name: "My section"
    groups:
    - name: "My group"
      technologies: ["pipeline"]
      vars:
        - name: "myvariable"
          widget: radios
          key: myvariable
          type: "string"
          default: foo
          values:
            - foo
            - bar
```

## Attributes constraints[​](#attributes-constraints "Direct link to Attributes constraints")

| Attribute name                                                              | constraints                                                   |
| --------------------------------------------------------------------------- | ------------------------------------------------------------- |
| [type](/reference/stackforms/concepts/variables.md#type)                    | `string`                                                      |
| [values](/reference/stackforms/concepts/variables.md#values-and-values_ref) | At least 1 values, if Boolean only 2 allowed (`true`,`false`) |


---

# simple\_text

```
widget: simple_text
```

* Rendering
* Code

![widget](/assets/images/simple_text-c4327a1604b8b19638d22e17fbdbebd4.png)

.forms.yml

```
use_cases:
- name: "Demo usecase"
  sections:
  - name: "My section"
    groups:
    - name: "My group"
      technologies: ["pipeline"]
      vars:
        - name: "Simple text widget"
          widget: simple_text
          key: myvariable
          type: "string"
```

## Attributes constraints[​](#attributes-constraints "Direct link to Attributes constraints")

| Attribute name                                                              | constraints    |
| --------------------------------------------------------------------------- | -------------- |
| [type](/reference/stackforms/concepts/variables.md#type)                    | `string`       |
| [values](/reference/stackforms/concepts/variables.md#values-and-values_ref) | Not compatible |


---

# slider\_list

```
widget: slider_list
```

* Rendering
* Code

![widget](/assets/images/slider_list-b423421d972484e169a32a3fbbb0ca4a.png)

.forms.yml

```
use_cases:
- name: "Demo usecase"
  sections:
  - name: "My section"
    groups:
    - name: "My group"
      technologies: ["pipeline"]
      vars:
        - name: "integer"
          widget: slider_list
          key: myvariableint
          type: "integer"
          default: 2
          values:
            - 1
            - 2
            - 3

        - name: "string"
          widget: slider_list
          key: myvariablestr
          type: "string"
          default: a
          values:
            - a
            - b
            - c

        - name: "boolean"
          widget: slider_list
          key: myvariablebool
          type: "boolean"
          default: true
          values:
            - true
            - false
```

## Attributes constraints[​](#attributes-constraints "Direct link to Attributes constraints")

| Attribute name                                                              | constraints                                                   |
| --------------------------------------------------------------------------- | ------------------------------------------------------------- |
| [type](/reference/stackforms/concepts/variables.md#type)                    | `string`, `boolean`, `integer`                                |
| [values](/reference/stackforms/concepts/variables.md#values-and-values_ref) | At least 1 values, if Boolean only 2 allowed (`true`,`false`) |


---

# slider\_range

```
widget: slider_range
```

* Rendering
* Code

![widget](data:image/png;base64,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)

.forms.yml

```
use_cases:
- name: "Demo usecase"
  sections:
  - name: "My section"
    groups:
    - name: "My group"
      technologies: ["pipeline"]
      vars:
        - name: "myvariable"
          widget: slider_range
          key: myvariable
          type: "integer"
          default: 42
          values:
            - 1
            - 100
```

## Attributes constraints[​](#attributes-constraints "Direct link to Attributes constraints")

| Attribute name                                                              | constraints                                                |
| --------------------------------------------------------------------------- | ---------------------------------------------------------- |
| [type](/reference/stackforms/concepts/variables.md#type)                    | `integer`                                                  |
| [values](/reference/stackforms/concepts/variables.md#values-and-values_ref) | Only 2 values accepted, mininimal value first then maximum |


---

# switch

```
widget: switch
```

* Rendering
* Code

![widget](/assets/images/switch-c62df6210d9ac47c7428068b679342ef.png)

.forms.yml

```
use_cases:
- name: "Demo usecase"
  sections:
  - name: "My section"
    groups:
    - name: "My group"
      technologies: ["pipeline"]
      vars:
        - name: "myvariable"
          widget: switch
          key: myvariable
          type: "boolean"
          default: true
        - name: "myvariable2"
          widget: switch
          key: myvariable2
          type: "boolean"
          default: false
```

## Attributes constraints[​](#attributes-constraints "Direct link to Attributes constraints")

| Attribute name                                                              | constraints              |
| --------------------------------------------------------------------------- | ------------------------ |
| [type](/reference/stackforms/concepts/variables.md#type)                    | `boolean`                |
| [values](/reference/stackforms/concepts/variables.md#values-and-values_ref) | Does not take any values |


---

# text\_area

```
widget: text_area
```

The text area widget allows users to input various types of data, such as maps, arrays, or multiline text. It provides a large space for free-form text, and can also be used to allow users to provide samples or scripts, such as userdata for cloud init.

* Rendering
* Code

![widget](/assets/images/text_area-dd152f71c647a19adc2a1aaa813b2987.png)

.forms.yml

```
use_cases:
- name: "default"
  sections:
  - name: "My section"
    groups:
    - name: "My group"
      technologies: ["pipeline"]
      vars:
        - name: "text"
          widget: text_area
          type: "string"
          key: mytext
          default: this is a text area

        - name: "array"
          key: myarray
          widget: text_area
          type: array
          default:
          - subnet-id1
          - subnet-id2

        - name: "map"
          key: mymap
          widget: text_area
          type: map 
          default:
            tags:
              foo: 1
              bar: "test"

        - name: "multi text"
          key: mytext2
          widget: text_area
          type: string
          default: |-
             This is just
             a text
```

## Attributes constraints[​](#attributes-constraints "Direct link to Attributes constraints")

| Attribute name                                                              | constraints    |
| --------------------------------------------------------------------------- | -------------- |
| [type](/reference/stackforms/concepts/variables.md#type)                    | any            |
| [values](/reference/stackforms/concepts/variables.md#values-and-values_ref) | Not compatible |


---

# Stacks

<!-- -->

In Cycloid, a stack refers to our primary automation concept.

A stack describes a generic infrastructure, service, or workflow using the principles of GitOps and Infrastructure as Code (IaC). This results in code stored within a Git repository.

In technical terms, a stack serves as a template that can be used repeatedly to obtain the described infrastructure or services. Additionally, it provides a means to customize parameters each time it is used.

Stacks can be shared with all users as an available list of "services"

![stack-list](/assets/images/stack-list-8c14deb77cf0b2a92e7cab5de0a23068.png)

**Who would use it?**

There are primarily two types of individuals who would be interested in stacks: users and maintainers.

Here's a concrete use case to illustrate its utility:

Imagine a company with two distinct teams: the "infra" team, responsible for managing infrastructure and servers, and the "app" team, responsible for developing and testing applications.

The infra team's responsibility is to ensure that all servers, networks, and other infrastructure components adhere to standardized patterns and best practices. Meanwhile, the app team focuses on developing and testing applications. To facilitate proper testing, the app team often requires temporary infrastructure to deploy new application releases and conduct tests.

The infra team aims to streamline the process of provisioning infrastructure, enabling the app team to work autonomously. However, they also need to maintain governance and control over access and resources used by the app team.

This is where stacks come into play. The infra team can create stacks that describe the servers and infrastructure required by the app team. The app team can then utilize these predefined stacks to deploy temporary infrastructure with minimal effort.

In this scenario, the infra team serves as stack maintainers, while the app team acts as stack users.

![stack-concept-users-kind](/assets/images/stack-concept-users-kind-b3cd431bb761851023349c8689d9d070.png)

Consider scaling this concept to a larger context, where you can describe various types of infrastructure, workflows, or service deployments. You can provide these predefined stacks as part of a catalog available to all users within the organization.

Keep in mind that use cases are not limited to that; we have plenty of other examples in our documentation to illustrate what you could actually do.

## Introduction[​](#introduction "Direct link to Introduction")

This documentation primarily targets stack maintainers, aiming to provide comprehensive insights into the composition of a stack and best practices for designing new ones. If you are a stack user, you can refer to the [getting started](/cookbook/getting-started/.md) guide for instructions on creating a project using an existing stack.

In essence, a stack serves as a template utilizing infrastructure as code, capable of defining infrastructure, services, or workflows that can be shared with other users.

Stack code should be stored in one or several Git repositories. These repositories need to be added to your Cycloid organization and referred to as [catalog repositories](/reference/config-and-catalog-repository/.md).

You have the option to create your private stacks in your Git repository or utilize public stacks provided by Cycloid.

### What does a stack contain?[​](#what-does-a-stack-contain "Direct link to What does a stack contain?")

note

To enhance the efficiency and flexibility of stacks, Cycloid recommends and simplifies a specific way to organize your IaC files. We refer to this approach as the **stack concept**, which works alongside stack and config. While it's a best practice, it's not mandatory if you prefer to maintain your code structure differently.

A stack requires at least two components: a file named `.cycloid.yml` and a **pipeline**. When you add a new catalog repository to Cycloid, our API clones the Git repository and searches for any `.cycloid.yml` files in the root directory or the first layer of subdirectories.

* **.cycloid.yml**: This metadata file, defined by Cycloid, contains information such as the stack's name, icon, description, and the path to the IaC files.
* **A stackforms definition**: stackforms define the variables of your stack that will be filled by the stack user.

Most of our `stacks` rely on open-source projects such as:

| Technologies                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | Description                                                |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
| ![Git](data:image/png;base64,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) | Stores application and IaC source code                     |
| ![Terraform](data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAZAAAAB9CAYAAACMEjUkAAAABGdBTUEAALGPC/xhBQAAACBjSFJNAAB6JgAAgIQAAPoAAACA6AAAdTAAAOpgAAA6mAAAF3CculE8AAAABmJLR0QAAAAAAAD5Q7t/AAAACXBIWXMAAFiVAABYlQHZbTfTAAAAB3RJTUUH5QkHBhoN0IuAjQAAFYVJREFUeNrt3Xm0XWV5x/HvHTLPCQYwCWFIIEAUyyTGIhjTKjPUIEUFbQsiigKttV0GXV1qusqSLoYCUspQEGJVaDWgS2iIDGUSigwNFAwkoYQQEiCBm0uSO/WP397cnZOz99lnunufc36ftbIIuSc7e+9zzn7e93mf933BzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzBpPW5b/+KL5y977/eLlC7K+F2ZmVob2rE8gFA0mZmaWf3kIIAcBs0FBxIHEzKwx5CGAHA/cAZwHTAEHEjOzRpBpAImMe+wHXAb8DDgRGAFOa5mZ5VkeeiChDuDjwK3AvwCHAm3ujZiZ5VOeAkhoLHAG8Avgu8BMcFrLzCxv8hhAQu8HLgKWAmcBE8CBxMwsL/IcQEIfBK4GfgJ8EhgGHh8xM8taIwQQUND4JAoiV6Og4t6ImVmGGiWAhCagdNZSlN6aBg4kZmZZaLQAEpqJBth/jgbcx4HTWmZmQ6lRAwhoHa9DUcnvLagEuNO9ETOzodHIASQ0Ak0+vA1NRtyfjBeJNDNrBZ1Zn0ANTQa+ChwMnLRo/rIN4Q/yvNKvVyQ2s0bVTAEktBvqlXSiRRpfXDR/2XbI1wO6IM02DRgAXs36vMzM0mqGFFahfvQwHg78ALiGnJX9Rs5hHPAFNOv+Y1mfl5lZOZqxBxIaACYCxwGfQIPtNwJrwwf4UPdIIoGjEzgKuAD4I9RjasZgbmZNrNkfWgPBf/cgw7Lfgp7PgcAVaOXh41Hw6M/6RpmZlauZeyCFomW/C1HF1gOL5i/rhfr0RgoC1G4oXfUlYO+sb4aZWbVaKYCEwrLfPwR+DFwFPFfrtFYkeIwBTgDOBw6n+Xt91pg6gPehhs4UYHTw59uAt4E3gY3AZqAv65O1fGjFABIKy34/hQbafwSsrzaQRAJHB/ARNM5xLDAq6ws2K2IcWmfuZFQCvysKHuGzoQ/YDrwDvA68ANwJLMGBpOW1cgAJ7QNcDPwJSmvdCXQvmr+srCBSkK6aDZwLfB616vKmjex7Qn74ZO9AYDFqRI2IeU1n8LNxaIuFD6HG0ZKsT96y5wAi7ai38CEUQC4HHl40f1k/JPdGCgLHLsDnUPDYL+uLSrA/sIj4h0a9bQK+g+e9ZGkO8K9oXLBcq3ADwHAAKTQKOBWV2P4IpbZWxqW1IsFjJHAMSld9FLXQ8mxqcJ3DMvr3NwKX4ACSlVHAt6kseACsyfoCLB+yTmNAPlsyU4G/Au4AvoYGFd8LGJGy3DY0MH49CjgfI//BA1Te3Jvhv9/LYIm1Db0jUGFHJXqA/8v6Aiwf8hBAbkcP4M1Zn0gRc4BL0UKNJzE4EN4G7AX8PZpb8llUbWXWCI4hmAtVQi+qwuphMOBvwz1HC+QhhfV74CvoIX0hWpY9q9RKMR3A0ai7fzHwfRQ8/g04LOuTMyvTKOCQEq9Zh8ZHHgO60fdxCjADmIR7IBbIQwABlQn+GngE5ea/Bnwg65MqMBZVrYC+RHkeJDeLMx5VU8XZhgosbsz6RC3/Mk9hLV6+IDo4vQnNFD8BlRfmrascLjkyQGMvP9JGtmM1jTBO1KzGoMZQnFeB7FcctYaQlx7Ie0EkGJxeg6pEfgF8HU1yGlvhoW1nq1EqLm2qcDoqTx4e8/O3gZuBt1Ierwt4I+ub0KKGkfy+bwa2ZH2S1hhyE0BCkUAygHKwZ6PxkQuAI3HrtRZWA98r4/WHo9RiUgC5BJd3NoNe8lkZaTmUeQorTiSttRX1RBaiQfb/zfrcWlCaoO3AbtZichtAYKfxkTeAf0LjI/+I1uWx5tKO0ivDg19Zfj7bMjxW4X0YVsN7UWrsboD69EA66nQ9lajlexvVGbm+as8vfP9z3TDLXQqrmILxkZXAN4H/QCvcHo8XKmxUk4ED0I6Rs9FKsOPQw6UfjZW8hhbwexJ4FhVapDEelVsXe1isA9YX+fOwxPVYtKTNQ8GfDwNmUXzpl3eAl9h5YmQ7mkd0HLABlcUW/nwSsDvar2YG2tp4KtoIbQyDD4/e4N/ZgNKPzwX34hWSJ2SOCs47+hDak+Tv/Wi0pE9XzM/fRd/BpCDTCcwE5qL3dyZa5mdU8H70B9ezHngRWBFcz2uk0xFcV7HvfXdwfoWBsg2te3dscD9/GLl3MwgmCxd4LeGcxqL3bb/g157ovRsZHH8dqiq9i+RioPbg3uyNlhiajcYcJwb38V001WE58EDw/7nREAEkFAkk/cCDwO9QADkfza7NdY/K3rMncDoqjtifdJPa3gaeRvNvfooepkkOB26leGvwSrQWV2gM2rXyz9Ccn4nAywwGkClopYFi+7j8FqVXwwduB1rV9ouotzwjOOeb0UNtBHAa2onyQPSwmED8+FIxW4PzWw7cFJxDsZ7FPmii66TIn3WQXJAyB63AEBeYngBOQQGg0OjgPp4OzEPlwmla490oCN+FFmn8HcmBcTyq1pxb5GfPoUm/G4P/b0MNlDOD894LuBu4Dk0fAKXGv1jkWD9GUwrCezsFvbfzg+vbN/izuGs8K7hfi4J/M9SOvgPzgvt1CAqy44jvHX0VpfIvQo2IXGioABJavHxB2BvpRg+T+9BOg+eiL0i9uqhWnU7g0+gLVe48n/FoD5d5wTH+Fj044wxDD85iX+45DJYyHw2chx7ooyOvmRr5fTt6yE8qcqzZwbl1odb2l4HPoGXRQ1NQgNganM85wXVUaiR6eO2LHoqXovRud8HrOoJznlTGsTtQAI3TTvFlcA5AD7cTKX9VhtEoGMxFqzpci3btfDPm9W3Evx/7oPu9EfVSzg6OOT3ymkmo9xIGkDExxzoK9RAnBff5+OAcR5NOO5qAfC3wp8Az6H0/FQWOmaRPUY1FlZDjUUMnF1WMDRlAYKe01npUBfQr9CZvw0EkbzrRigPfRV/+SrWj1QpuRl+kh2NeN0B8K3YGakn+OWotF3t47JbyfCainsRpKBAV66WE6Zut6CG/iuoCSNSu6J6OREvr9BS5D7W0qci/MQ+lhD5Yg+Pvjkr490eVl+tiXhd3XeOCv3sU6lnMKfKaSeiBvLnEsfZGyyzNRenFSs1EW0W8gdbLq2ZKwrFom4jLqzhGzTRsAAkVBJJng19tqJXQKEGkFVJvJ1N98IjaDxVTLKT8CacHAv+OcthxdkXfj1KLTo5HqzYntSYnogfbWygdsrJG9yA0HD0sH0UrOtRT4Y6Ec6hd8Ai1o15cN0ohdZXxd0eiz8V04tOC49HncG2JY41Cm23VwodrdJwO1OgpZ95V3TTNg6ugYmsAtfZuIP9lv93AT0hOxzS66Si9UavgEToC9ULKbSiMIzl4gDYCS7NfSidqqSalIsIHVqjYIG+1JqDU2MgaH7fQZgZb7COBb1Hb4BH1WZT6KUc7ej+SxpTGoAKORnUA6mVlruF7IIUiPZI+FEDuR3npM9gxr521fpR+uQz4JTmrrqixhZQe8+hHi/StRgO0I9FDfi/iBynb0APmBuJTHZWaih40tZiVPZYdd6ZcjfLvI4Pr7kat7LeD/3ajNFF7cA5TUEqtVLXhPDQm80zknr7LjmMj7SgwxgXdfpQCjkvrRMvn56GeZRqb0fvahx7uEyg9ljAcjWsupbZl+6PZcYyq0YxFPb+Hqj1QtZougER0oNzzSuCvUdnvBaisMuuy35Wo238LzT+fZSyqiknq7a5DaYefB7/vQe/fFLT0+LeJ7zHsi1ZFXlrDc34HrYJQiz1TelFVUXRAeBWqAnodlWi+gqrK3kYP/HA2eDgfYAJKu52Dxvjieju7AAcxGEBWoVRQNADPQAPUcQPrL6C9cOIC50vBf9tRMUNSBd0A8DhKtzwWXGMfCmAzgAUonz894RgfQOMGt9XgvQAFyKepzfeuK7imruB+TqOytHkfSkdtDH4/jeRChrbg/mWumQPIKFSd8jz6sj6ISupOQIHkwwx9Cu8NVKZ4NZHUWjl7rzegvRhcxbiYLhTgby348x6Uo74OpSOvpXjgH45KdmsRQLrQGMJ1qOa+u4pj9aExievQnJJo2fFatMZb2gHuzahs93FUdXh0zOvaUUCNXk9hK3UWg9VHxbyDeu2lxh0mo6q4JHei8tNiy7+/ANyD7vf1qHqqmGGoaOL2Mu5XMf1oLtENaPwr7ZyTQhtRuvkeFBTXoM/JZOAbwF+Q7rnSixoP9we/VqBioD6UorocNQbiTKziXtRMMweQATSweToKGlegD85PgXuBL6AW3T4VHr8cW1GN+6XAfxEMQjZ54AjNIrmM9EH0viT5FSqOiNvHYg7pBrzj9KA5FVeiB0O16cRnUA/zNuLnq1TyMNwQ3KujiG/plqoeK1U2mnal5nDyY5z1wN9Reu+Q+9DD8tKEfzcsna00nfgCaoAsobJUZ39wjNtRL3kFO39GNgbXcRLJqfItwTUvQc+hV9n5s3Afyk4kBZBy5g3VTTMHEBgcqDwEfYAWog/qfcAPGGwhnU59BtXCLvzlaBJQF7RM4AjNIPlz9iilH9ibUGstLoDshsYTyqnWCf0Pen9+RvW7Yq5HLdx/pn4LS65CgTJuXCg6k7+eppFcjvrf6N6m8Z8opbR7zM93R2m8cgPIm+hBfBUKAJUYQI2BSyg9ge8tlIaMCyAbUVXZHSmuZX3wb8c1FHKxxEmzB5CoEagn8lE0w/QqNGv166hlcSHwx6SrvEljNZoteyORVk+LBQ8oPYktTS66H30x44xD71s5AWQzWl7kCgbz+pXqQamYi1HKqJ77vW8nOTiEa4jVO4BMJvn58RLJqbKo10kOIGMpb3JiH2rd/wPwG6pb22sgOMbqMl4f563gWE2zXH4rBZDQZNTr+BRqKd6M3tTH0GzT89Eks0rnkGxCabIrGRzMbMXAESrV1e4nXc446f0YTvmf5d+gsZeeMv9eMWvRuFq1gSitpHsxVON6w0ucRznjR30kB5twkcK03kLjEU/W6Fpr1drPeiO3mmvFABLaB7VQTkGltHeg9Y7uQTOUz6b0XIGo7cHfvQw9nHqgpQNHqFQgPgutLVTKwVX8G8WE1U610MPQlWH3Ud8eTlpDeQ7tlBcYe2nusvjcaOUAAvpQfgStPvpL9PB/CO3WtxTlK0+l9AS4p1Aq5DaCVIsDR2oHkxwc6qmN2j0Iq1n1YDyalzAZpWqSHpaH0kQTgOukjcZZhaKhtXoACY1CA+wfQ72Qa1Ct+LlofOQCtPhZR7BkStgVXYtKEK9HZZaAg4el0oaKAj6DymH3QGM5pVJD4V4hZplzANnRVDSJ6jg0V2MJGhx9GFVq7YK+3FvRAOxNqNoEcOCw1EagcbhvED9wbJZ7DiDFzUHlvp8O/vtr1CsZiVIezwN/SZBDd+CwMrShyWbfJ/sVEcyq4lxqvA40YesWlKI6jMFKkV4cPPKkkRpCs1Av18HDGl4jffGyEm7k8nHUavyhg0ZNPYJ6dJVqQ/NsGqXq5hi0vItZw3MASe/9aJD9GvJRRtksbkLzcarVCO9JB5rImjRIvgYtq7IWrYpbaBZagDDr+QRDWeWUtDmYZcgBpDz1nt3bjErNAm6ndR4OY9Fe2HHWo/1N7iX+nnwCLWGfdQAp9b6WUylWaoJdL7WZ8Gk15jEQq7dSy4vUepOpPBtV4nqfpvRSKB3kY45D4c6EhaaTPshNIHktundpnBRlS3EAsXp7neQH4hxa53PYSXLLfBON09JeR/JyJX9A8j4fUYeRXM68keoXurQ6aJUvrmVnNcmtx6MpvVthnBE01qS6fpJb7eMonVbOy3f2ZZRyi7M3mutSaovdGWjFh6RFTJ+nspWWrc7y8mG05vV7NCAcZw+0nPqRJG9x2ok20dkXOBbtUngbqo5rFN1ow6Y4c9FmQsXsgvaauIB8BM31aIO2OO3AeWiJnyPQqszhopcjUY/jRLSY6ZEJx+knsoeO5YsH0a3eXkObRs1OeM1RaKOeJ9BOjRvQwGkbWhtqMtrzYxqqhpvCYIv1MeDurC8ypS2o5R639td0tAXAragaqy247rloB80DKN2iHyo96D07hfiANgotSroQ7WOyHs2lGoveyz1TXM/LaJFSyyEHEKu3XrQkTKn9syejPbLLnWQzl+p2IxxKPWiDsZMTXnNo8CsMoFlXWyW5CzUOji7xukmU3hemmAEUTIdqmXwrk1NYNhTuR0GkHvYjJ/tDp3Q38EaK13WS7+AB2vFvMek2BavEQ2g3QJfP55QDiA2FbWgWfz1STdNJ3ps7b55CKzw3i+XAt1AwqaWn0OZua6s9kNVPsweQvLfgWskrwJdQSmJblceKGgfMzPriyrAdbX37SIV//0m05UBeyn370bbN5wAranC8XrS525lEVrq2fGrmALIduJP6da9bTdJnJe3EtjXoQXMW2rXxnZR/r9AWNNi+JDjewzHnVItzTvP6cr9HLwX34A7S7RveDfwWbcF7IvA9VGhQ6XW1VfizOP2oIu4klNJ6jvIDXBfwANqD50w0qXKorqGWxxqqz1weJpM29SB6D2rp3YtKH48juUzU4q1C6YS4apstaLJXGlvQCsdL0U6Q84CDUDnvFFS504kGUMOtYjejCp7VaE7As6g8eD3x5Z0rUBlp3Bd6JemXUNkMfIf4WeSbKX+i2wrgDLS44gnAgWiguQMFlU2oAulJNFD9BINjJ8OD9+N9RY67iuQxg/XA3xC/GvAGKp/1/SJwEVov7nBUvrs/qrgajyrn2lEvYytKe61hcAb+k8F1l9KNAtWUmJ+/i6r/0lpC/P7pA6TvCdXyc/Io8JWEnz9bxvXVTS6iWL0EuweCAsdxKJAcQeU9ryXA5xcvX9AqazcNlXZUrjsGlXVGA8hWBpeyaIRKq0p0oEKAcCLhdtQ76yI/qapKDWfwvR2Bnjl96H3dEvzyHI8G1dQBBHYIIqAdB89EaY9ZFRzOAcTMLNDMYyCANnyK7N/xOnAJyiNfSbpySjMzK6LpA0ioIJA8B1yIZsgupbZVQWZmLaFlAkgoEkh60QD759ByC4/TOvtSmJlVreUCSCjSG+lCdfUnoQqKNVmfm5lZI2jZAAI7pbVeRbOlTwSuw/sPmJklaukAEioIJE+j+uvT0GJxjV5GaWZWFw4gEZEg0oOCx2komISzYn2/zMwCTT8PpFIF80dmAl9GM7G/uXj5Aq8OamYtzwGkhEggaUdLTbzpiYRmZg4gqUV7JJFUl5mZmZmZmZmZmZmZmZmZmZmZmZmZmZmZmZmZmZmZmZmZmZmZmZmZmZmZmZmZmZmZmZmZmZmZmZmZmZmZmZmZmZmZmZmZmZmZmZmZmZmZmZmZmZmZmZmZmZlZw/p/F0mGurMRp6UAAAAldEVYdGRhdGU6Y3JlYXRlADIwMjEtMDktMDdUMDY6MjY6MTMtMDQ6MDBp4B+IAAAAJXRFWHRkYXRlOm1vZGlmeQAyMDIxLTA5LTA3VDA2OjI2OjEzLTA0OjAwGL2nNAAAAABJRU5ErkJggg==)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Describes the infrastructure and services                  |
| ![Ansible](/assets/images/ansible-78261904d7b5f09d56843212ca6192ec.png)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | Deploys and configures applications inside the target      |
| ![Concourse](/assets/images/concourse-7d5bfd92567e81cdc128778fa90b3744.png)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | Provides a `pipeline` to describe and execute any workflow |

Note

While these technologies are the most commonly used, it's important to note that you can use any tools you prefer (e.g., Helm, Kubectl, Cloud providers' APIs, Salt, Puppet, Chef, etc.). Don't hesitate to reach out to Cycloid engineers for assistance.

### How can I obtain or create stacks?[​](#how-can-i-obtain-or-create-stacks "Direct link to How can I obtain or create stacks?")

Currently, there are three ways to acquire stacks:

1. **Use Public Stacks**: Gain access to public stacks provided by Cycloid or the community by adding new **catalog repositories** to your organization. Refer to the [stack list reference](/reference/stacks/reference/public-and-community-stacks.md) for more details.

2. **Create from Scratch**: Build a new stack from scratch using the [blueprint feature](/reference/stack-blueprint/.md), which guides you through the process step by step.

3. **Import Existing Resources**: Create a new stack from existing resources on a public cloud provider using the [infraImport feature](/reference/infra-import/.md). This feature enables you to import infrastructure configurations and settings into a new stack effortlessly.

## Pre-requisites[​](#pre-requisites "Direct link to Pre-requisites")

For a stack user, the only requirement is to add a configuration repository in your organization. If you don't already have one, refer to [add a new config repository](/reference/config-and-catalog-repository/.md).

For a stack maintainer, if you intend to create your own private stack or use a public one, you'll also need to [add a catalog repository](/reference/config-and-catalog-repository/.md).

## Quickstart[​](#quickstart "Direct link to Quickstart")

If you are a **stack user**, we recommend starting by following the [getting started: how to use a stack](/cookbook/getting-started/end-users/.md) before diving deeper into the concept.

If you are a **stack maintainer**, the next section will cover how to design a stack, details on configuration files, and how to organize Infrastructure as Code (IaC) files. If you're interested in creating a new stack, you can follow our [Create a stack step-by-step guide](/cookbook/getting-started/devops-teams/stack-creation/.md), or if you're already an advanced user, you can create a stack from scratch using [blueprint feature](/reference/stack-blueprint/.md).


---

# Design a stack

After grasping the concept of stacks composed of the **stack** and **config** parts, it's beneficial to explore examples to determine which approach best suits your use case before commencing the stack writing process.

## Understanding the right approach[​](#understanding-the-right-approach "Direct link to Understanding the right approach")

As mentioned earlier, the concept of stacks serves as a method to organize Infrastructure as Code files. Alongside this concept, it's crucial to take the time to determine what should be included in a `stack`.

A common question from our customers is, "How can I integrate my current application into a Cycloid stack?"

There's no one-size-fits-all answer to this question. The `stack` concept offers significant flexibility, allowing the stack creator to define its contents.

There are three major considerations that guide the design of a stack:

* **Goal of the `stack`:** What service or application are we aiming to package? And who will be the primary user of the stack?
* **Application dependencies:** What infrastructure and deployment dependencies does the application have?
* **Security and political restrictions:** Are there any specific security policies or teams responsible for certain resources?

The design choices made for a `stack` can impact its:

* **Reusability:** A highly specific stack may be challenging to reuse in other projects.
* **Maintenance and complexity:** The more resources and use cases a stack contains, the more challenging it becomes to maintain and update the infrastructure as code.

With these considerations in mind, let's explore two concrete examples of applications and how they could be defined as `stacks`. Additionally, you can learn more about [Terraform recommended patterns](https://developer.hashicorp.com/terraform/tutorials/recommended-patterns/pattern-module-creation?in=terraform%2Frecommended-patterns).

### Web Application Example[​](#web-application-example "Direct link to Web Application Example")

Consider a simple web application composed of compute instances built on top of a network VPC.

![Web Application](/assets/images/web-app-1-30f14fd13792dba83107e1cd580b1915.png)

**One approach** is to create an entire standalone `stack` containing all the resources needed for our **application**. Using infrastructure as code, we describe the VPC network and compute instances.

![Web Application](/assets/images/web-app-2-990981b6b5252139b1f0d9303bd22748.png)

With this approach, each user of the `stack` can deploy a fully standalone web application. The stack creates a dedicated VPC network and spawns the compute instances on top of it for each user.

Now, let's consider a **second approach** where we split this stack into two different ones: one for the network and one for instances.

![Web Application](/assets/images/web-app-3-ab4f0db250f37cc41b7889649d3bbde5.png)

In this scenario, the application is no longer standalone. Instead, users can create a shared network using the `network stack` and deploy multiple instances using the `instance stack` on this shared network.

Using the stack concept in Cycloid, you can link stacks together and allow users to select the network previously created by the `network stack` when deploying their applications using the `instance stack`.

In cases of shared responsibilities across teams, the network team could create a network project on the Cycloid dashboard based on the `network stack`. Developers could then deploy their applications with the `instance stack` using the network created with the **network project**. Access to projects can be limited using [Cycloid role and policies](/reference/organizations/concepts/permissions.md) management.

![Web Application](/assets/images/web-app-projects-52a3f55e88520e43afcee8cc19f1ec82.png)

This approach is applicable to other components like object storages, databases, etc., offering flexibility and scalability in application deployment architectures.

### Kubernetes Example[​](#kubernetes-example "Direct link to Kubernetes Example")

At Cycloid, we extensively deploy containerized applications in Kubernetes. Let's explore how we achieve this using `stacks`.

Simplifying our workflow around Kubernetes, it can be categorized into two main use-cases:

* Creating and managing the Kubernetes cluster
* Building container applications from source code and deploying them on a Kubernetes cluster

![Kubernetes](/assets/images/k8s-1-a2315637510ee0016c751aa3398f10de.png)

To address our requirements, we split them into two distinct `stacks`:

* One manages the infrastructure aspect: creating a Kubernetes cluster, managing access, etc.
* The other defines the entire application workflow: from source code to build process and deployment on a Kubernetes cluster

![Kubernetes](/assets/images/k8s-2-76b3254778763ccf6d8592ce3c948d3d.png)

On the Cycloid dashboard, we establish a Kubernetes project based on our `infrastructure stack` and an application project based on our `application stack`. This separation enables us to manage our Kubernetes cluster and deploy multiple applications on top of it.

![Kubernetes](/assets/images/k8s-projects-3850dbe132a9596f1fc2b4d0f58a22d3.png)

All this functionality is available within our `public stacks`. We offer various infrastructure stacks to create Kubernetes clusters on different cloud providers:

* [Scaleway Kapsule](https://github.com/cycloid-community-catalog/stack-kapsule)
* [Azure AKS](https://github.com/cycloid-community-catalog/stack-aks)
* [Google GKE](https://github.com/cycloid-community-catalog/stack-gke)
* [Amazon EKS](https://github.com/cycloid-community-catalog/stack-eks)

Our application stack, facilitating the building and deployment of containers on Kubernetes clusters, can also be found in our public stack named [k8s-runner](https://github.com/cycloid-community-catalog/stack-k8s-runner).

## Additional Design Examples[​](#additional-design-examples "Direct link to Additional Design Examples")

Stacks can be highly useful for managing infrastructure, deployments, or CI/CD jobs. However, it's important to remember that a pipeline within a stack can describe much more. A pipeline delineates a workflow to automate or simplify any actions.

You can automate or describe nearly any workflow in a pipeline. The **resource** approach of a pipeline allows you to interact with almost all existing external software. More details about pipeline specifics and configuration will be provided in the dedicated pipeline section.

If you want to obtain more example of internal and customer use cases you can read the [Stack Examples section](/reference/stacks/examples/stack-examples.md)


---

# Infrastructure as code and GitOps

Cycloid stacks follow 2 main concepts, GitOps and Infrastructure as code (IaC). Before going more in details about stack it's important to understand those both approach.

## GitOps[​](#gitops "Direct link to GitOps")

GitOps is an approach that uses Git as the source of truth for infrastructure and application deployment, enabling declarative configuration, tracking changes in Git history, continuous deployment, automated operations, observability, and immutable infrastructure practices.

With Git serving as the core of delivery pipelines, developers utilize familiar tools to expedite and streamline application deployments and operational tasks.

**Beyond stacks, Cycloid provides a range of features designed to maximize the benefits of the GitOps approach:**

[Infra Import](/reference/infra-import/.md) facilitates the creation of automation by your DevOps team from existing infrastructure.

## Infrastructure as code (IaC)[​](#infrastructure-as-code-iac "Direct link to Infrastructure as code (IaC)")

### What & why IaC?[​](#what--why-iac "Direct link to What & why IaC?")

Infrastructure as code (IaC) revolutionizes infrastructure management by enabling the provisioning and management of computer data centers through machine-readable definition files instead of manual configuration or interactive tools. This paradigm shift is propelled by the advent of cloud computing, which offers API-driven environments conducive to automation, shorter lifecycle durations, and enhanced scalability. As a result, IaC has gained popularity in recent years, facilitated by the DevOps movement.

IaC has gained immense popularity in recent years, especially with the evolution towards DevOps practices. It involves managing infrastructure through code, streamlining deployment, and ensuring consistency across various environments.

**Examples of Infrastructure Level IaC Tools:**

| Example tools                                                                                                       | Description                                                                                                                                         |
| ------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| **[Terraform](https://www.terraform.io/)**                                                                          | An open-source infrastructure as a code software tool that provides a consistent CLI workflow to manage hundreds of cloud services                  |
| **[AWS CloudFormation](https://aws.amazon.com/cloudformation/)**                                                    | A template describes your desired resources and their dependencies so you can launch and configure them together as a stack                         |
| **[Google Cloud Deployment manager](https://cloud.google.com/deployment-manager/docs/)**                            | An infrastructure deployment service that automates the creation and management of Google Cloud resources                                           |
| **[Azure Resource Manager](https://docs.microsoft.com/en-us/azure/azure-resource-manager/resource-group-overview)** | A deployment and management service that provides a management layer that enables you to create, update, and delete resources in your Azure account |

**Application and configuration management tools**:

| Example tools                                  | Description                                                                         |
| ---------------------------------------------- | ----------------------------------------------------------------------------------- |
| **[Ansible](https://www.ansible.com/)**        | Automates application deployment, configuration management, and continuous delivery |
| **[Puppet](https://puppet.com/)**              | Simplifies infrastructure and workflow management                                   |
| **[Chef](https://www.chef.io/chef/)**          | Empowers policy-based configuration management automation                           |
| **[Salt-stack](https://docs.saltproject.io/)** | Delivers intelligent, event-driven automation for various operational functions     |

### Drawbacks and Benefits[​](#drawbacks-and-benefits "Direct link to Drawbacks and Benefits")

While Infrastructure as Code (IaC) offers numerous advantages, there are some drawbacks worth considering.

1. **Initial Setup Time:** Setting up IaC may initially take longer than traditional methods. Ensuring that all infrastructure configurations are properly documented and translated into code can be time-consuming.

2. **Slower Small Changes:** Making minor adjustments or updates to infrastructure configurations through IaC can be slower compared to manual changes. For instance, modifying a DNS entry directly in a console might be quicker than locating the corresponding file in the code repository, making the necessary updates, committing the changes, and applying them.

Despite these challenges, the benefits of IaC far outweigh its drawbacks.

Firstly, by automating your infrastructure management with IaC, you enhance the **robustness** and **reliability** of your day-to-day operations, significantly reducing the risk of human error. This automation also serves as an effective means of documenting your infrastructure, as all configurations are meticulously recorded.

The automation introduced by IaC facilitates **continuous delivery** and fosters a collaborative environment. With automated processes in place, versioning your infrastructure code becomes crucial, providing valuable insights into your infrastructure's evolution and enabling effective collaboration among team members.

Moreover, IaC promotes **transparency** and **accountability** by providing a comprehensive history of all changes made to the infrastructure. This detailed record includes information about who initiated the changes and who approved them, ensuring greater visibility and traceability.

Through IaC, your infrastructures and environments become more **reproducible**, making it easier to create new environments and maintain consistency across deployments. This reproducibility also reduces the likelihood of unexpected environment shifts, contributing to better management and control.

Additionally, IaC enables infrastructure configurations to be **reusable** across different projects, enhancing efficiency and minimizing duplication of effort.

Harnessing the flexibility of the cloud and IaC, you gain better **control** over the **cost** of your infrastructure, allowing you to optimize resource utilization based on usage patterns. You can easily scale resources up or down, start or stop environments as needed, and implement cost-saving measures.

For further insights, various industry leaders such as [Microsoft](https://docs.microsoft.com/en-us/devops/deliver/what-is-infrastructure-as-code), [HashiCorp](https://www.hashicorp.com/resources/what-is-infrastructure-as-code), and [Puppet](https://puppet.com/docs/puppet/7/puppet_language.html) offer valuable resources and information on IaC.


---

# Stack concept

On top of the technical aspects of a stack described in the previous sections, Cycloid also introduces best practices and methods for organizing Infrastructure as Code (IaC) to enhance the flexibility and maintainability of a stack.

Cycloid advocates for the adoption of [Infrastructure as Code](/reference/stacks/concepts/iac-and-gitops.md) and encourages users to structure their code using the concept of a **Stack**.

Important

The stack concept serves as a **framework for organizing** infrastructure as code and related files. It is not mandatory; users have the flexibility to choose whether or not to implement it in **any tools and software they want**.

***

The **stack** concept resolves around creating a re-usable piece of automation that can be easily instanciated and configured by your end users.

This could be anything, from creating infrastructure to managing an app deployment or executing a script.

To illustrate this concept, consider a **tree** analogy. From the perspective of Cycloid, the `stack` serves as the blueprint outlining the structure of the tree, including its roots, trunk, branches, and leaves. However, not all users desire the same tree; each may prefer a different color.

This is where Cycloid introduces `config` for a stack. In our tree analogy, the `stack` defines the tree's shape, while the `config` allows users to select the color of their tree. As a result, all trees maintain the same structure outlined in the `stack`, with individualized colors specified by users in their respective `config`.

![stack concept trees](/assets/images/stack-concept-trees-08d54f05b00e438feb24acffd1fd50a8.png)

To accomplish this from a technical standpoint, we introduce the concepts of `stack` and `config`:

![stack concept](/assets/images/stack-concept-full-9568f358499659a87105a700aa5148bf.png)

The culmination of merging the `stack` and the `config` results in what we term a `configured stack`.

The stack is developped by the stack maintainer, and the configuration if filled by the user using [StackForms](/reference/stackforms/.md).

To understand a little bit these two sections, let's use a basic example of a [LEMP stack](https://github.com/cycloid-community-catalog/stack-lemp):

* A `stack` serves as a generic description of an application. In our example, we define servers using IaC on which we install an Nginx web server and PHP, connected to a database.
* The `config` is filled by the user and is tied to a [component](/reference/projects/concepts/components.md) in and [environment](/reference/projects/concepts/environments.md). In our LEMP example, this includes the number and size of the servers to create.

**Cycloid typically operates with a stack and config definition stored in a Git repository**, created respectively in `stacks` and `config` branches. Stack and configuration definitions could be in either **public** or **private** Git repositories.


---

# Stack definition

As previously defined, a Stack in Cycloid is a crucial component that follows the infrastructure as code approach, typically comprising a set of files stored within a Git repository (Your own Git repository).

Understanding how to define a stack can be summarized into two key points:

**1. Structure**: A Git repository may contain one or multiple stacks. To define a stack, you need to provide a `.cycloid.yml` file within the stack directory. This file serves as metadata, containing essential information such as the name, description, keywords, and other relevant metadata defining your stack.

Additionally, you have to include a `.forms.yml` file at the same level as your `.cycloid.yml`. This file defines the stack user inputs.

![forms-create](/assets/images/forms-create-db8375928fa1d719b72992d5329ae757.png)

**2. Definition**: Defining new stacks in Cycloid involves specifying, at the organization level, the *Git repositories* and potential *credentials* required to fetch them. This process, known as the **catalog repository**, essentially defines the Git repository containing stacks within the Cycloid dashboard.

Once the Git repository is connected to Cycloid, our API fetches its content, making the stacks available across Cycloid interfaces.

Stacks can originate from various sources, including your own private Git repository, as well as community stacks provided by Cycloid. You can explore the list of community stacks [here](https://github.com/cycloid-community-catalog).

For further details on these main points, refer to the following sections.

## Stack structure[​](#stack-structure "Direct link to Stack structure")

**First stacks directories**

As mentioned earlier, Cycloid stacks are code in a Git repository. Those files have to be put in a git repository which can be your own private or public Git. However, there are actually two ways to organize stacks in Git:

* **Multiple stack** repository: This is the most common approach. You can place several stacks in a Git repository by creating a subdirectory for each stack. Usually we call this branch in Git `stacks`.
* **Single stack** repository: Place only one stack at the root level in a Git repository. This is typically used to create a community stack, providing a dedicated Git repository for public GitHub stacks, for example.

To sumup, in a git repository you can create one or several `stacks`: one at the root level or several stacks in subdirectories (maxdepth 1). Those stacks can be created in a branch of your choice, might it be named `stacks` or whatever you prefer the most.

In both way the architectures and files for a stack are exactly the same.

### Using a pipeline[​](#using-a-pipeline "Direct link to Using a pipeline")

**Usual files in a stack**

If you are Using **Multiple stack** repository architecture, you should find at the top level of your Git one directory for each stacks. For example `stack-infrastructure`, `stack-network`, `stack-myApp`, ...

In each directories, one **.cycloid.yml** file, at least `.forms.yml` file.

./stack-myApp

```
├── .cycloid.yml
├── .forms.yml
```

Let's go through a more complete example. Complexe stacks to manage entier infrastructures and applications usually contains also Terraform and Ansible code

Note

Ansible and Terraform are not required, you could use either onemptied, both or something else. Those are the most common used in our stacks. But you are not limited to those tools.

The directory of this kind of stacks would usually looks like this:

./stack-myAdvancedApp

```
├── ansible
│   └── site.yml
│   └── variables.sample.yml
    └── ...
├── .cycloid.yml
├── .forms.yml
├── pipeline
│   ├── pipeline.yml
│   └── variables.sample.yml
├── README.md
└── terraform
    └── provider.tf
    └── main.tf.sample
    └── ...
```

* **Pipeline** (template): Main component to orchestrate and define the workflow. The pipeline is in charge of using described technologies in the right order based on an external trigger such as a Git commit, ... [Concourse Triggers Docs](https://concoursetutorial.com/basics/triggers.html)
* **Terraform**: Used to create and maintain a target infrastructure on any cloud providers. Contains Terraform module definition ([Terraform Modules](https://www.terraform.io/language/modules)), required variables and outputs...
* **Ansible**: Used for the configuration management and continuous deployment. Configure and install services inside target servers and handle the deployment of your application. Contains, Ansible roles, playbook and variables.
* **Custom**: Used to execute any template files with Cycloid [special variables](/reference/stacks/concepts/templating.md#special-variables) and user-defined variables configured via [StackForm](/reference/stackforms/concepts/forms-file.md).
* **.cycloid.yml**: File containing the name, description and the configuration of the stack in the catalog. [Format reference](/reference/stacks/reference/cycloid-file.md).
* **README.md**: A file in a markdown format where you usually write stack usage documentation. The name of the file is not case sensitive, you can use different name such as `readme.md`, `Readme.md`, ...
* **.forms.yml**: A file containing the [stackforms configuration](/reference/stackforms/concepts/forms-file.md) in order to offer to users a nice visual way to provide user inputs.
* **...samples files**: Files linked to stackforms and concept of stacks. See details below\...

### Sample Files[​](#sample-files "Direct link to Sample Files")

In Cycloid, the concept of stacks involves organizing files to separate generic components (stack) from specific user inputs (config). Sample files play a crucial role in this process alongside stackforms.

Here's how it works:

![stack-sample](/assets/images/stack-sample-1ccfeeab59f055a80adddd0dd9d4ced3.png)

A stack can utilize various Infrastructure as Code (IaC) technologies like Terraform, Ansible, and more. Stackforms acts as a bridge between a user and an IaC code, collecting user inputs and converting them into the correct format for your IaC.

This is where sample files come into play. To generate a correct user input file, stackforms needs to know the expected format, which depends on how it will be used in your Terraform or Ansible code.

The sample file provides a clear example of how user inputs are expected to be structured. This file is stored in the `stack` branch as a reference file.

When creating a new component, stackforms reads the sample file and uses it to generate and write the user inputs file (in the correct IaC format) in the **config repository** at the `destination` path. The file structure inside the configuration repository is defined in the `.cycloid.yml` file. Details about this file are explained in the reference section.

If you need more flexibility in organizing your infrastructure, you can use the Custom Technology.

This technology lets you use the [go text/template engine](https://pkg.go.dev/text/template) to generate file for any usage (for example, Kubernetes) that can be populated with stack form values and project-specific settings.

## Stack visibility[​](#stack-visibility "Direct link to Stack visibility")

The visibility of a stack determines its availability within or beyond an organization. Cycloid provides three visibility levels to manage stack accessibility effectively:

#### - **Local**[​](#--local "Direct link to --local")

The stack is available only within the current organization where the catalog repository is defined.

Note

By default, a stack's visibility is set to **local** unless explicitly configured otherwise. This ensures that stacks are initially restricted to the organization where they are created or imported, maintaining privacy and control.

#### - **Shared**[​](#--shared "Direct link to --shared")

The stack is shared across all organizations within your Cycloid platform.

Important

**shared** stacks are propagated exclusively from parent organizations to their child organizations; they are not accessible in the reverse direction. For optimal governance and consistency, it is advisable to define **shared** stacks at the root-level organization, ensuring streamlined maintenance and standardized access.

#### - **Hidden**[​](#--hidden "Direct link to --hidden")

The stack is not visible to regular users by default but can be accessed through specific filters. This is ideal for development or testing.

By default, stacks inherit the visibility of the **catalog repository** at the time of import. For example, if the repository's default visibility is set to **local**, all imported stacks will adopt the same visibility. This visibility setting is determined during import and cannot be changed afterward. To modify the visibility of a stack post-import, you must set the visibility individually for each stack.

danger

Be careful when changing the visibility of a stack from a parent organization.

If you change the visibility of a `shared` stack from a parent organization to `local` or `hidden`, all child organizations will lose access to the stack.

> This means all projects that depend on this stack will be broken.

We are actively working to prevent this in a future patch.

## Maintainer[​](#maintainer "Direct link to Maintainer")

Each stack can be assigned a maintainer, a designated team responsible for its management. Maintainers oversee updates, ensure compliance with organizational standards, and handle issues related to the stack's functionality.

Note

The maintainer attribute is optional and intended for informational purposes only and does not enforce access control or permissions within the platform.


---

# Templating

Note

* **1)** This section requires an understanding of the [.cycloid.yml file](/reference/stacks/reference/cycloid-file.md) format and potentially [stack usecases](/reference/stacks/concepts/use-cases.md).
* **2)** In order to use templating, you should ensure your `.cycloid.yml` file uses at least the **version: 3**.

A templating language is a syntax used to generate text/code dynamically by combining static content with dynamic data or logic.

In order to make stacks even more flexible, Cycloid introduced a templating language that you can use inside stack files.

This templating enable dynamic content generation by allowing Cycloid variables such as organization, project, and also create conditions or loops in any sample files, `.cycloid.yml`, `.forms.yml`, pipelines, terraform samples and custom files.

You can also use our new Custom Technology to create any file with the templating engine. In this case, you will also have access to StackForms variables.

.cycloid.yml

```
---
version: 4
name: 'mystack'
...
```

## Stackforms variables[​](#stackforms-variables "Direct link to Stackforms variables")

<!-- -->

Using the Custom Technology you can use any stackforms variable:

```
($ .variable_name $)
```

The variable name can contain `.`, this is useful when sharing variables with module scope with the terraform technology:

* Stack configuration
* Stackforms
* Terraform
* Template source
* Template output

.cycloid.yml

```
---
version: '4'
name: 'Templating with terraform'
canonical: 'templating-with-tf'
author: 'Cycloid'
config:
  default:
    custom:
      var_path: ($ .config_root $)/cy_vars/file.json
      templates:
      - paths:
        - source_templates/main.tmpl
        destination: ($ .config_root $)/dest_file.yml
        config:
          destination_is_file: true
```

.forms.yml

```
use_cases:
- name: "use_case"
  sections:
  - name: "section"
    groups:
    - name: "group1"
      technologies: [terraform, custom]
      vars:
      - name: "Some shared var"
        key: module.foo.hello
        type: string
        widget: simple_text
        default: "foo"
    - name: "group2"
      technologies: [custom]
      vars:
      - name: "Some var only for the Custom Technology"
        key: bar
        type: string
        widget: simple_text
        default: "There"
```

main.tf.sample

```
module "foo" {
  hello = "foo"
}
```

```
foo: ($ .module.foo.hello $)
bar: ($ .bar $)
```

```
foo: foo
bar: There
```

## Special variables[​](#special-variables "Direct link to Special variables")

<!-- -->

Variables can be used in any sample files, `.cycloid.yml`, `.forms.yml`, terraform samples, ansible and pipelines. It can also be used by the Custom Technology, in that case, you will also have access to stackforms variables.

To use a variable, follow this format:

```
($ .variable_name $)
```

Here is the list of all the available special variables:

Reminder

Resources `canonicals` is the unique name attributed on a resource.

Resources `names` are the pretty names of a resource displayed on the UI, it can change and is not reliable.

Always use the `canonical` in your code and automations for resources reference.

<!-- -->

| Variables                                       | Description                                                                                                                                                                         |
| ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ```
($ .org $)
```                                | Org canonical.<br />*Aliases: organization, org\_canonical, organization\_canonical*                                                                                                |
| ```
($ .org_name $)
```                           | Org name.<br />*Alias: organization\_name*                                                                                                                                          |
| ```
($ .env $)
```                                | Env canonical.<br />*Aliases: environment, env\_canonical, environment\_canonical*                                                                                                  |
| ```
($ .env_name $)
```                           | Env name.                                                                                                                                                                           |
| ```
($ .component $)
```                          | Component canonical.<br />*Alias: component\_canonical*                                                                                                                             |
| ```
($ .component_name $)
```                     | Component name.                                                                                                                                                                     |
| ```
($ .project $)
```                            | Project canonical.<br />*Alias: project\_canonical*                                                                                                                                 |
| ```
($ .project_name $)
```                       | Project name.                                                                                                                                                                       |
| ```
($ .project_owner $)
```                      | Canonical of the project owner (usuallaly, the user who created the project).<br />*Alias: project\_owner\_canonical*                                                               |
| ```
($ .project_owner_name $)
```                 | Project owner name.                                                                                                                                                                 |
| ```
($ .project_owner_surname $)
```              | Project owner surname.                                                                                                                                                              |
| ```
($ .project_owner_email $)
```                | Project owner email.                                                                                                                                                                |
| ```
($ .catalog_repository $)
```                 | Catalog repository canonical.<br />*Alias: catalog\_repository\_canonical*                                                                                                          |
| ```
($ .catalog_repository_name $)
```            | Catalog repository name.                                                                                                                                                            |
| ```
($ .catalog_repository_url $)
```             | Catalog repository git URL where the stack is located.<br />*example: `git@github.com:cycloidio/...git`*                                                                            |
| ```
($ .catalog_repository_branch $)
```          | The branch of the catalog repository where the stack resides.<br />*example: `stacks`*                                                                                              |
| ```
($ .catalog_repository_credential_type $)
``` | The type of credential used to access the stack's service catalog.<br />*possible values: `basic_auth`, `ssh`*                                                                      |
| ```
($ .catalog_repository_credential_path $)
``` | The path of the credential used for the catalog repository. See the [credential section](/reference/credentials/quickstart.md#create-a-credential) for more details about the path. |
| ```
($ .stack $)
```                              | Stack canonical.<br />*Alias: stack\_canonical*                                                                                                                                     |
| ```
($ .stack_name $)
```                         | Stack name.                                                                                                                                                                         |
| ```
($ .stack_path $)
```                         | The path of the stack in the catalog Git repository, basically the directory where the `.cycloid.yml` file is located.                                                              |
| ```
($ .config_root $)
```                        | Alias to do `($ .org $)/($ .project $)/($ .env $)/($ .component $)` which is our default `destination` config path pattern.                                                         |
| ```
($ .config_repository $)
```                  | Config repository canonical.<br />*Alias: config\_repository\_canonical*                                                                                                            |
| ```
($ .config_repository_name $)
```             | Config repository name.                                                                                                                                                             |
| ```
($ .config_repository_url $)
```              | The URL of the config repository configured for this stack.<br />*example: `git@github.com:cycloidio/...git`.*                                                                      |
| ```
($ .config_repository_branch $)
```           | The branch in the config repo holding the configuration for the stack.<br />*example: `config`.*                                                                                    |
| ```
($ .config_repository_credential_type $)
```  | The type of credential used to access the stack's config repo.<br />*possible values: `basic_auth`, `ssh`*                                                                          |
| ```
($ .config_repository_credential_path $)
```  | The path of the credential used for the config repository. See the [credential section](/reference/credentials/quickstart.md#create-a-credential) for more details about the path.  |
| ```
($ .inventory_jwt $)
```                      | The JSON Web Token used to access the inventory. See the [inventory usage](/reference/inventory/concepts.md#how-to-use-it-in-a-pipelines-) section for more information.            |
| ```
($ .api_url $)
```                            | The URL of the Cycloid API.<br />\*example: `https://http-api.cycloid.io`.                                                                                                          |
| ```
($ .console_url $)
```                        | The URL of the Cycloid console.<br />\*example: `https://console.cycloid.io`.                                                                                                       |
| ```
($ .use_case $)
```                           | The use case name of the stack. See the [Use cases](/reference/stacks/concepts/use-cases.md) concept for more informations.                                                         |

### Usage example[​](#usage-example "Direct link to Usage example")

The following example show usage of Special variables as default values in a stackforms widget:

.forms.yml

```
use_cases:
- name: "Demo"
  sections:
  - name: "My section"
    groups:
    - name: "My group"
      technologies: ["pipeline"]
      vars:
        - name: "Virtual machine name"
          widget: simple_text
          key: vm_name
          type: "string"
          default: "($ .project $)-($ .env $)-($ .component $)"
```

Another example in `.cycloid.yml` file. Using special variables to define a dynamic destination for the variables file.

.cycloid.yml

```
...
config:
  demo:
    name: 'this is the demo use-case'
    pipeline:
      pipeline:
        path: 'pipeline/pipeline.yml'
      variables:
        path: 'pipeline/variables.sample.yml'
        destination: '($ .org $)/($ .project $)/($ .env $)/($ .component $)/pipeline/variables.yml'
        # Or better, use the `config_root` special var that does the same as the above
        destination: '($ .config_root $)/pipeline/variables.yml'
```

## Templating any files with Custom Technology[​](#templating-any-files-with-custom-technology "Direct link to Templating any files with Custom Technology")

When using Custom Technology, all Special Variables are automatically supported.

You can use them within your template files just like you use other keys defined in a stack form. For example:

* Template
* Stackform
* Template result

```
This is a content of my template. It will be part of a project ($ .project_name $).
Within this file I can use a variable defined by a stack form too: ($ .stackform_variable $).
```

.forms.yml

```
use_cases:
- name: "default"
  sections:
  - name: "section1"
    groups:
    - name: "group1"
      technologies: [custom]
      vars:
      - name: "Stackform variable"
        key: "stackform_variable"
        type: string
        widget: simple_text
        default: "My cool stack"
```

```
This is a content of my template. It will be part of a project My project.
Within this file I can use a variable defined by a stack form too: My cool stack.
```

## Functions[​](#functions "Direct link to Functions")

<!-- -->

Cycloid templating languages support function from the [Sprig library](https://masterminds.github.io/sprig/).

Here is an example template utilizing a function, followed by the rendered output.

* Template
* Output

```
# environment: "my-env-prod"
my upper environment: ($ upper .env $)

# project: "my-project"
my replace project: ($ .project | replace "-" " " $)

# environment: "my-env-prod"
is my env end by prod ? ($ regexMatch "-prod$" .env $)

# environment: "my-env-prod" & project: "my-project"
($- $concatVar := printf "%s_%s" .project .env $)
concat project and env: ($ $concatVar $)"
```

```
# environment: "my-env-prod"
my upper environment: MY-ENV-PROD

# project: "my-project"
my replace project: my project

# environment: "my-env-prod"
is my env end by prod ? true

# environment: "my-env-prod" & project: "my-project"
concat project and env: my-project_my-env-prod"
```

## Conditions and loops[​](#conditions-and-loops "Direct link to Conditions and loops")

Basic conditions and loops can be used in the templating language.

<!-- -->

Here is an example template utilizing a conditions and loop, followed by the rendered output.

* Template
* Output

```
# use_case: "aws"
($- if eq .use_case "aws" $)
Here is my special AWS use_case code ...
($- else if eq .use_case "gcp" $)
Here is my special GCP use_case code ...
($- else $)
Here is my default code
($- end $)

# environment: "prod"
($- if or (eq .env "prod") (eq .env "demo") $)
Specific action for prod or demo
($- end $)

# template definition
($- define "myTemplate" $)
  echo "foo"
  echo "($ .use_case $)"
($- end $)
($- template "myTemplate" . $)

# Define a map
($- $mapdata := dict "key1" "value1" "key2" "value2" "key3" "value3" $)
($- range $key, $value := $mapdata $)
Key: ($ $key $) Value: ($ $value $)
($- end $)
```

```
# use_case: "aws"
Here is my special AWS use_case code ...

# environment: "prod"
Specific action for prod or demo

# template definition
echo "foo"
echo "aws"

# Define a map
Key: key1 Value: value1
Key: key2 Value: value2
Key: key3 Value: value3
```

## Template escape characters[​](#template-escape-characters "Direct link to Template escape characters")

Template escape characters are essential in templating languages to prevent certain characters or sequences from being interpreted as template syntax. This is important when you need to include literal characters or sequences in the output that would otherwise be treated as part of the template logic. Escape characters ensure that the template engine processes these characters correctly and outputs them as intended.

Consider a situation where you want to include the literal string `my_raw_($ string $)_output` in your output.

`($` and `$)` are used to delimit template actions. To include them in the output without invoking the template processing logic, you need to escape them.

<!-- -->

To escape content, please put it between ``($ ` ``and `` ` $) `` delimiters.

* Template
* Output

```
My escaped string:
($ `my_raw_($ string $)_output
  identation and
newlines are supported too` $)
```

```
My escaped string:
my_raw_($ string $)_output
  identation and
newlines are supported too
```

## Tools[​](#tools "Direct link to Tools")

To assist you in writing your own template stack, you can use the [tmpltui script](https://github.com/cycloidio/tmpltui/tree/main) to validate and preview the rendered template.


---

# Use-cases

## What is a stack use case?[​](#what-is-a-stack-use-case "Direct link to What is a stack use case?")

As we have already seen, stacks address a need using Infrastructure as Code (IaC). It is crucial to study a need thoroughly when designing a stack to understand how to structure it.

In order to offer more flexibility, Cycloid also provides a way for a stack to implement "use cases". Use cases are a way of implementing slight differences in a stack by providing different **pipeline or sample files**.

During environment creation, all available use cases for a stack will be displayed to the user.

Let's consider two main scenarios where it could be useful:

**First scenario**: You have a stack to create a virtual machine (VM) on AWS using Terraform. To do so, you need to write specific Terraform code for AWS, assuming we put this code under the `terraform/aws` directory. Tomorrow, you want to extend this stack to also offer a way to create the VM on GCP. To achieve this, you will need to write specific Terraform code for GCP under the `terraform/gcp` directory.

In technical terms, depending on which cloud provider your end user wants to create their VM, the Terraform code used will point to a different directory.

To address this, you could create two use cases for your stack: one for AWS and one for GCP. This way, by selecting the AWS use case, your stack could target the appropriate Terraform path by specifying a different sample file such as `terraform/aws/main.tf.sample`.

![stack-usecase1](/assets/images/stack-usecase1-e0fb63a8f620864a50ddc1d03a32d14f.png)

**Second scenario**: You are building a CI/CD pipeline for an application. You want to deploy this application on different environments such as `staging` and `production`. Both environments will be deployed on the same kind of infrastructure, but you would like a different CI/CD workflow. For example:

* The `production` workflow would trigger an automatic backup before any deployment and then check monitoring status as a post-deployment task.
* The `staging` workflow would run functional testing and load testing after a deployment to detect any performance regressions.

In this case, you would probably use the same IaC files to deploy your application, but you will require a different pipeline to describe a distinct workflow for both environments. To achieve this, you can create a `production` use case with its own pipeline and a `staging` one with another pipeline.

![stack-usecase2](/assets/images/stack-usecase2-0f6719fc386f5c95004f4664bf720ceb.png)

**In summary**: Use cases are designed to make stacks more flexible by offering more choices to the end user when using your stack. Use cases allow you to provide different pipelines or sample files.

## How to define a usecase ?[​](#how-to-define-a-usecase- "Direct link to How to define a usecase ?")

Use cases are defined in the `.cycloid.yml` file. For each use case, you can specify a specific pipeline path, sample files, or both. Remember that each use case also has to be defined in the stackforms `.forms.yml` file.


---

# Stack Examples

This section cover several example on how we solved various usecases using stacks and pipelines. It will provide design approach and idea on doing things

### Ephemeral Infrastructure[​](#ephemeral-infrastructure "Direct link to Ephemeral Infrastructure")

Internally, we had a need to deploy an ephemeral server with WordPress for demo purposes. This server had to be created automatically, and we also wished to ensure it was automatically cleaned up after the demo.

Our approach was to create a stack based on Terraform. The stack is capable of deploying a WordPress application on any cloud provider.

![Stack](/assets/images/stack-demo-cycloid-cfadc66d71ef86307312e8cd61240884.png)

The second part of our required workflow is to trigger an automatic cleanup one hour after it has been deployed (approximately the time required for a demo).

We decided to handle everything as part of the pipeline `stack`. For this purpose, we created a dedicated **job** which is triggered automatically one hour after a demo.

![Stack destroy](/assets/images/stack-demo-destroy-0e2338a0f5c6b8f446dd99fde444822c.png)

To perform a proper cleanup, we need to call Terraform destroy to remove all cloud components, as well as the project created on Cycloid. To achieve this, the trigger part is done via the [time resource](https://github.com/concourse/time-resource) to trigger our cleanup job called **terraform-destroy** after one hour.

The **terraform-destroy** job will first use the [Terraform resource](https://github.com/cycloidio/terraform-resource) to perform a Terraform destroy, then use the Cycloid CLI to interact with our API and remove the Cycloid project.

This way, after a demo, everything that has been created on the cloud provider and Cycloid side is automatically deleted.

### Automatically Create Dedicated Environments for Developers[​](#automatically-create-dedicated-environments-for-developers "Direct link to Automatically Create Dedicated Environments for Developers")

When developing an application, it can be useful to create ephemeral infrastructure to test the current release under development in real-life conditions. This is what we do internally at Cycloid to test each new feature and enhance our developer experience.

We refer to it as a dedicated environment for feature branches. Internally, we work with GitHub, where each feature or bug is developed in a dedicated Git branch. Once it's ready, we initiate a GitHub pull request.

Our objective was to automate the creation of a dedicated environment when a new pull request is opened and remove it when the pull request is closed.

![Stack dedicated-env](/assets/images/stack-dedicated-env-3aa24ff7c45141da78a75f8ec742f7b3.png)

First, we create a Cycloid stack for our automation, focusing on our frontend application. Our stack covers two use cases:

* CI/CD: Employed for the building or deploying of our application.
* External automation: Used for GitHub-specific automation (dedicated environment).

We won't cover the CI/CD part, as it's a generic pipeline to handle application deployment. Instead, we'll focus on external automation.

This pipeline mainly contains one automation job called "*create dedicated env*".

![Stack dedicated-env](/assets/images/stack-feature-branch-pipeline-966b478d7fa93a5bd7e56b7f75d5235f.png)

We call this pipeline job the "watcher". The job relies on the [GitHub pull request resource](https://github.com/telia-oss/github-pr-resource) to watch and trigger the job for any new pull request created.

Each time a new pull request is created, the pipeline is automatically triggered, and the job `create-dedicated-env` actually adds a new environment to the project `cycloid-frontend` using our [Cycloid CLI](/reference/cli/.md).

The environment is named based on the GitHub pull request ID `PR_<pull request id>` and is composed of a CI/CD pipeline to create and deploy a temporary infrastructure.

![feature-env-sumup](/assets/images/feature-env-sumup-23a8f8cecb3c700dcb75f413a2592a4e.jpeg)

Our watcher is triggered by GitHub pull requests. The watcher pipeline creates a dedicated environment pipeline for each pull request. The dedicated environment pipeline handles the deployment and the creation of the temporary infrastructure.

![frontend-project](/assets/images/frontend-project-a2be58beea5b5112643a5b8e681e0e06.png)

Now let's have a look at an automatically created environment, such as *PR\_4999*.

This environment contains a pipeline split into two main sections:

* Deployment
* Cleanup

**Deployment**: This part is a simple pipeline that builds and deploys our application in a new temporary environment. Each time a new commit is detected, it builds the code and deploys it on the dedicated infrastructure to test the code in a live environment. Additionally, we've added an extra job called *url-in-comment* to write a comment in the GitHub pull request, informing our developer that the environment is available and providing the URL.

![feature-env-pipeline](/assets/images/feature-env-pipeline-62ca3e1608eecbdcc7e4a39537d2fe94.png)

**Cleanup**: This second section of the pipeline is similar to the previous use case explained in *Ephemeral Infrastructure*. It contains a job dedicated to triggering an automatic cleanup when the pull request is closed or merged. To do so, we use Terraform destroy to remove the infrastructure part, and Cycloid CLI to remove the project environment automatically.

![feature-env-cleanup](/assets/images/feature-env-cleanup-7e96bdd25eb94ba11eb479335dd522b2.png)

### Automate Daily Tasks[​](#automate-daily-tasks "Direct link to Automate Daily Tasks")

As demonstrated in previous use cases, pipelines are versatile tools that can handle and automate complex workflows. However, it's important to remember that pipelines can also address simpler needs and automate basic tasks.

tip

Pipelines are not limited to CI/CD or infrastructure management tasks.

Many routine actions can be automated or streamlined for users through pipelines.

One approach is to create automation or dedicated jobs that users can trigger to perform simple tasks. For instance, setting a maintenance page on/off for a website:

![stack-job-maintenance](/assets/images/stack-job-maintenance-b8d33f23392153084ee70dd31116c227.png)

This example come from a customer's need to quickly set their entire infrastructure into maintenance mode with a single click. This involved running Ansible on several servers. To meet this need, we created a dedicated job that, when triggered, runs Ansible with the necessary arguments and sends a Slack notification to inform users that the task has been completed.

This is just one example from a multitude of possibilities. Almost any task you can imagine can be simplified and automated using a pipeline.

Here are some real-life examples of what our customers are doing with pipelines:

* **Flush Application Cache** (CDN, Varnish, etc.): Force the flush of the entire CDN and Varnish cache of an application with one click.

* **Automatic Rollback** of a Deployment:

  <!-- -->

  * Based on Functional Testing: Automatically run functional tests after a deployment and trigger a rollback if any failures are detected.
  * Monitoring Events: Listen for monitoring alerts after a deployment, and trigger a rollback if critical alerts are raised.
  * Deployment Failure: Automatically rollback in case of deployment failure.

* **Start and Stop** Servers or Services: Offer the ability for non-technical users to start or stop servers or services with one click.

* **Enable/Disable Monitoring**: Temporarily disable specific monitoring alerts during a deployment and re-enable them afterward.

* **Trigger Backups Before Deployment**: As part of the application deployment workflow, trigger a backup of the current application files or database before deploying the new version.

* **Dump Production to Staging**: Automate the process of dumping the production database, converting data, and injecting the dump into the staging database.

* **Release Watcher**: Monitor software releases and notify users when a new release is available.
  <!-- -->
  * Internally, we extensively use a **release watcher** to track Terraform releases. This ensures that we are always notified of new Terraform releases. Whenever a new release occurs, a message is sent to our internal developer channel.

### Integrating GitLab for CI and Cycloid for CD[​](#integrating-gitlab-for-ci-and-cycloid-for-cd "Direct link to Integrating GitLab for CI and Cycloid for CD")

This use case demonstrates how Cycloid can seamlessly integrate with existing CI tools, allowing for a flexible and efficient workflow. While Cycloid handles the CD part of the process, local development CI tasks can be managed by the development team using their preferred CI tool, such as GitLab.

Let's break down the process:

1. **Application and Kubernetes Deployment**: We have a Docker application that needs to be deployed on Kubernetes.
2. **CI with GitLab**: The CI pipeline in GitLab is responsible for testing and building Docker images.
3. **CD with Cycloid**: Cycloid handles the deployment of each new Docker image onto Kubernetes.

Following best practices, we recommend using Infrastructure as Code for all components. Therefore, the first step is to create a stack to manage the Kubernetes cluster:

![stack-gitlab-k8s](/assets/images/stack-gitlab-k8s-9f37ec858dc194f6eb5a59bb2c070433.png)

Now, let's visualize the workflow:

![stack-gitlab](/assets/images/stack-gitlab-08e0bb1a4b321532dd17e8a54351c560.png)

1. **Source Code Management**: The application's source code resides in a Git repository.
2. **CI with GitLab CI**: The GitLab CI pipeline executes unit tests and builds the Docker image.
3. **Docker Image Registry**: The built Docker image is pushed to a Docker registry.
4. **CD with Cycloid Pipeline**: Cycloid pipeline listens for changes in the Docker registry.
5. **Continuous Deployment**: Whenever a new Docker image is detected, Cycloid pipeline triggers the deployment process onto the Kubernetes cluster.

This setup allows for a seamless integration between GitLab's CI capabilities and Cycloid's CD functionalities, enabling a smooth and efficient workflow from development to deployment.

### Access Management with Cycloid[​](#access-management-with-cycloid "Direct link to Access Management with Cycloid")

As previously mentioned, stacks are not limited to infrastructure management at Cycloid. We apply the infrastructure as code and stack concepts across various aspects of our platform, including access management.

One such example is our IAM (Identity and Access Management) stack:

![stack-iam](/assets/images/stack-iam-9a0e336bcc83b054ff58b1c60cbf6830.png)

This stack, powered by Terraform, handles access management for a wide range of services, including public cloud providers like Scaleway, GCP, Azure, AWS, and many other tools such as GitHub:

![stack-iam-full](/assets/images/stack-iam-full-4a885f7db910999f248b91c9d089389b.png)

By leveraging Terraform's capabilities, we can efficiently manage access permissions across different services and tools within our platform, ensuring secure and streamlined access for our users.

### Kubernetes Deployment with Cycloid[​](#kubernetes-deployment-with-cycloid "Direct link to Kubernetes Deployment with Cycloid")

At Cycloid, we not focus on traditional infrastructure management but also leverage Kubernetes extensively. Many of our services are deployed and managed using Kubernetes within the Cycloid platform.

Let's delve into how we handle Kubernetes at Cycloid, outlining our current approach:

**Cluster Management**

We kickstart everything with a stack designed to manage our Kubernetes cluster on Scaleway (Kapsule) using Terraform:

![stack-kubernetes](/assets/images/stack-kubernetes-1d7141361cc6869befa7b8d2af3cbe01.png)

**Docker Image Builds**

Our stack approach extends to building Docker images as well. Depending on the complexity or size of the application:

* For larger or more complex applications, we utilize dedicated CI/CD pipelines.
* For smaller standalone projects, like those with a Dockerfile in a Git repository, we rely on our Docker build stack:

![stack-dockerbuilder](/assets/images/stack-dockerbuilder-736cd3dc20324414a165354d77729f73.png)

This stack takes a Git repository as input, builds a Docker image from a Dockerfile, and then pushes it into a Docker registry.

**Deployment on Kubernetes**

Internally, we employ three main approaches to deploy on Kubernetes, all encapsulated within a stack, tailored to the specific requirements:

* **Raw YAML Files**: Utilizing the kubectl Concourse resource, ideal for deploying Kubernetes YAML files sourced from the internet or custom ones.
* **Terraform with Kubernetes Provider**: This approach is useful when managing cloud provider resources alongside Kubernetes resources. It enables defining dependencies between applications and cloud services, leveraging Terraform plan for comprehensive visibility into changes.
* **Helm through Terraform Helm Provider**: Leveraging Helm charts, particularly useful for deploying upstream applications that provide Helm charts. Like the Terraform Kubernetes provider, it facilitates handling dependencies between cloud provider resources and Kubernetes resources.

We generally prefer Terraform-related solutions for Kubernetes deployments due to their ability to manage dependencies with other infrastructure resources efficiently.

***

tip

The use cases presented here are just a glimpse of the endless possibilities offered by Cycloid!


---

# Stack Templating Examples

This section cover several example on how we use templating in our Stacks.

### Configure basic\_auth or SSH credentials to access a Git repository[​](#configure-basic_auth-or-ssh-credentials-to-access-a-git-repository "Direct link to Configure basic_auth or SSH credentials to access a Git repository")

The Pipeline Git resource requires either SSH or basic\_auth configuration, both of which are distinct configurations depending on the Cycloid [credential type](/reference/credentials/concepts.md#ssh) used: To handle both access types, the following templating can be used.

* Template
* Output

pipeline.yaml

```
# Pipeline stack git repository
# scs_url: "https://github.com/cycloidio/my-stacks.git"
# scs_branch: "master"
# scs_cred_type: "basic_auth"
# scs_cred_path: "git_access"

resources:
- name: git_stack
  type: git
  icon: github-circle
  source:
    uri: ($ .scs_url $)
    branch: ($ .scs_branch $)
    ($- if eq .scs_cred_type "basic_auth" $)
    username: ((($ .scs_cred_path $).username))
    password: ((($ .scs_cred_path $).password))
    ($- end $)
    ($- if eq .scs_cred_type "ssh" $)
    private_key: ((($ .scs_cred_path $).ssh_key))
    ($- end $)

- name: git_config
  type: git
  icon: github-circle
  source:
    uri: ($ .cr_url $)
    branch: ($ .cr_branch $)
    ($- if eq .cr_cred_type "basic_auth" $)
    username: ((($ .cr_cred_path $).username))
    password: ((($ .cr_cred_path $).password))
    ($- end $)
    ($- if eq .cr_cred_type "ssh" $)
    private_key: ((($ .cr_cred_path $).ssh_key))
    ($- end $)
```

pipeline.yaml

```
resources:
- name: git_stack
  type: git
  icon: github-circle
  source:
    uri: https://github.com/cycloidio/my-stacks.git
    branch: master
    username: ((git_access.username))
    password: ((git_access.password))

- name: git_config
  type: git
  icon: github-circle
  source:
    uri: git@github.com:cycloidio/my-config.git
    branch: config
    private_key: ((git_key.ssh_key))
```

### Optional pipeline job[​](#optional-pipeline-job "Direct link to Optional pipeline job")

To reduce the amount of code to maintain, the same pipeline can be used for multiple use cases. However, some use cases may require a slightly different pipeline, such as having an additional job. Here is an example of how to add an optional pipeline job depending on the selected use case.

* Template
* Output

pipeline.yaml

```
groups:
- name: overview
  jobs:
  ($- if eq .use_case "aws" $)
  - awsjob
  ($- end $)

jobs:
($- if eq .use_case "aws" $)
  - name: awsjob
    plan:
    - do:
      - task: aws
        config:
          platform: linux
          image_resource:
            type: registry-image
            source:
              repository: cycloid/cycloid-toolkit
              tag: latest
          run:
            path: /bin/bash
            args:
            - -ec
            - |
              echo "AWS job"
($- end $)
```

pipeline.yaml

```
groups:
- name: overview
  jobs:
  - awsjob

jobs:
  - name: awsjob
    plan:
    - do:
      - task: aws
        config:
          platform: linux
          image_resource:
            type: registry-image
            source:
              repository: cycloid/cycloid-toolkit
              tag: latest
          run:
            path: /bin/bash
            args:
            - -ec
            - |
              echo "AWS job"
```

### Local dynamic variable[​](#local-dynamic-variable "Direct link to Local dynamic variable")

Template local variables can be defined and overridden depending on the conditions specified. This can be helpful to replace multiple occurrences with a variable. Here is an example of a Git dynamic path definition depending on the use case.

* Template
* Output

pipeline.yaml

```
# use_case: azure-linux

($- $stack_path := "" $)
($- if eq .use_case "aws-ec2" $)
  ($- $stack_path = "aws" $)
($- else if eq .use_case "azure-linux" $)
  ($- $stack_path = "azure" $)
($- else if eq .use_case "gcp-gce" $)
  ($- $stack_path = "gcp" $)
($- end $)

- name: git_stack
  type: git
  source:
    paths:
      - terraform/($ $stack_path $)/*
```

pipeline.yaml

```
- name: git_stack
  type: git
  source:
    paths:
      - terraform/azure/*
```


---

# .cycloid file

The `.cycloid.yml` is the main item of the **Stack definition**. This file contains all information of a stack, ranging from the name, description, and icon to available use-cases and the path of all sample files.

Note

If you manually add or remove a stack in the Git repository of your stack, or if you make any changes to a `.cycloid.yml` file, **a refresh** of the stack is **required**.

To do so:

1. Go to your `catalog-repositories` page.
2. Then click the `Refresh this repository` button next to your private catalog repositories.

Read more about the [**.cycloid.yml** file here](/reference/stacks/reference/cycloid-file.md).

## Example[​](#example "Direct link to Example")

.cycloid.yml

```
---
# version of the stack
version: '4'

# Pretty name of the stack, displayed in the UI
name: 'Lemp'

# canonical of the stack, it must be a unique identifier by org
canonical: 'stack-lemp'

# Description of the stack displayed in the UI
description: |
  This stack will deploy a LEMP web server on X Amazon EC2 instances behind an ELB load balancer, using RDS database and ElasticCache.

# List of arbitrary keywords to help user search for this stack
keywords:
  - 'lemp'

# Add the canonical of a user that is the author of the stack
author: 'Cycloid'

# link to a png icon sized 200x200 pixels to display on the UI for the stack
image: |
  https://raw.githubusercontent.com/cycloid-community-catalog/stack-lemp/master/icon.png

# List of technologies, this is only a description of what tools you use/deploy with this stack for the user
technologies:
- technology: Debian
  version: 11.x
- technology: Nginx
  version: 1.1x
- technology: Php
  version: 7.4

# if true, make this stack a blueprint to create other stacks
blueprint: false

# Define the configuration of the stack
# It's a map of use-cases with their configs
config:

  # The key is the use case identifier, use the same for defining stackforms
  # variables
  default:
    # Pretty name of the use case for the UI
    name: 'my default use-case'
    # Description of the use case for the UI
    description: 'this is the default'
    # You can add a cloud provider for related features
    cloud_provider: 'aws'

    # Pipeline configuration
    pipeline:
      pipeline:
        # path to the pipeline definition
        path: 'pipeline/pipeline.yml'
      variables:
        # path to the variable file in the stack
        path: 'pipeline/variables.sample.yml'
        # variable file destination in the config repository
        destination: '($ .config_root $)/pipeline/variables.yml'

    # Ansible configuration
    ansible:
      web:
        # path to the variable file in the stack
        path: 'ansible/environments/web.yml.sample'
        # destination path in the config repository
        destination: '($ .config_root $)/ansible/web.yml'

    # Terraform configuration
    terraform:
      main:
        # path to the teraform sample in the stack
        path: 'terraform/main.tf.sample'
        # destination path of the terraform file in the config repository
        destination: '($ .config_root $)/terraform/main.tf'

    # Custom Technology configuration
    custom:
      # Custom Technology will write the stackforms variables in a file
      # set the path here.
      var_path: ($ .config_root $)/cy_vars/file.json
      # Define the templates
      templates:
      # list of path, files or folder to evaluate
      - paths:
        - source_templates/main.tmpl
        - common/
        # list of helper path to add for each template evaluation
        helpers:
        - parts/
        - common.tmpl
        # destination path in config repository
        destination: ($ .config_root $)/dest_file.yml
        # configuration of the templating
        config:
          destination_is_file: true
      - paths:
        - source_templates/
        - common/
        destination: ($ .config_root $)/dest-folder/
```

## Argument Reference[​](#argument-reference "Direct link to Argument Reference")

* **version**: Version of the `.cycloid.yml` file. Latest version is `4`.

* **name**: Name of the stack displayed.

* **canonical**: Unique name within the organization. Should contain only lowercase alphanumeric `a-z`, hyphen `-`, or underscore `_` characters, with a length between `3` and `30`.

* **description**: (Optional) Details displayed to the user for the stack on the UI.

* **keywords**: (Optional) Keywords to simplify stack search on the interface.

* **author**: Author of the stack.

* **image**: (Optional) URL to an icon in png format with size `200×200` used for displaying the stack.

* **technologies**: (Optional) List of `technology|version` used in the stack. It's a free key/value section where you could list software and services used.

* **blueprint**: (Optional) Boolean (default: false) if true, this stack will be a [stack blueprint](/reference/stack-blueprint/.md).

* **config**: This section contains a map of [stack use-cases](/reference/stacks/concepts/use-cases.md) definition and source path and destination path of sample files.

  <!-- -->

  * **\<use-case canonical>**: Keys are the stack use-cases. This name also refers to and should match the use-case name in `.forms.yml` file in stackforms. In the example above, the use case is called `default`.

  * **name**: Display name of the use-case for the UI.

  * **description**: Details of the use-case for the UI.

  * **cloud\_provider**: Cloud provider the use-case is using. Values: `aws` [Amazon Web Services](https://aws.amazon.com/), `google` [Google Computing Service](https://cloud.google.com/), `azurerm` [Microsoft Azure](https://azure.microsoft.com/en-us/), `flexibleengine` [Flexible Engine](https://www.orange-business.com/en/solutions/cloud/flexible-engine), `openstack` [OpenStack](https://www.openstack.org/).

  * **pipeline**: Definition of the pipeline technology described in [Stack definition](/reference/stacks/concepts/stack-definition.md) section and also used by stackforms technologies.

    <!-- -->

    * **pipeline**:
      <!-- -->
      * **path**: `Relative path` of the YAML pipeline template to use.

    * **variables**:

      <!-- -->

      * **path**: `Relative path` of your configuration sample.
      * **destination**: `Relative path` to commit in your [config repository](/reference/config-and-catalog-repository/.md) where the rendered sample file will be uploaded.

  * **ansible**: Definition of the Ansible technology described in [Stack definition](/reference/stacks/concepts/stack-definition.md) section and also used by stackforms technologies.

    <!-- -->

    * **\<sample-name>**: Map sample configuration file. You can specify one or several sample files this way.

      <!-- -->

      * **path**: `Relative path` of your configuration sample.
      * **destination**: `Relative path` to commit in your [config repository](/reference/config-and-catalog-repository/.md) where the rendered sample file will be uploaded.

  * **terraform**: Definition of the Terraform technology described in [Stack definition](/reference/stacks/concepts/stack-definition.md) section and also used by stackforms technologies.

    <!-- -->

    * **\<sample-name>**: Map of sample configuration file. You can specify one or several sample files this way.

      <!-- -->

      * **path**: `Relative path` of your configuration sample.
      * **destination**: `Relative path` to commit in your [config repository](/reference/config-and-catalog-repository/.md) where the rendered sample file will be uploaded.

  * **custom**: Defines configuration of the Custom technology described in [Stack definition](/reference/stacks/concepts/stack-definition.md) section and also used by stackforms technologies.

    <!-- -->

    * **var\_path**: A path to the file where are stored the StackForms values selected by a user. It will be created in the config repository on component creation.

    * **templates**: A list of templates, each of them having its own configuration - source and destination paths.

      <!-- -->

      * **paths**: A list of input paths where template files reside. They can be given as a file or a directory. Each path must exist in stack configuration.
      * **destination**: Where the template files will be saved in config repository after execution.
      * **helpers**: Where common template parts are stored. Template parts that are commonly used across the templates can be extracted into a helper.
      * **config**: Optional template-specific configs.
        <!-- -->
        * **destination\_is\_file**: defines whether the destination should be a file or a directory.

**Config section details**

As described in the [stack definition](/reference/stacks/concepts/stack-definition.md#stack-structure) section, a stack contains file samples. These samples, after rendering by stackforms, are saved in Git under a config repository.

The path of the source sample file and the destination in the config repository are provided in this section.

Based on our previous example:

```
        path: 'ansible/environments/web.yml.sample'
        destination: '($ .config_root $)/ansible/web.yml'
```

Assuming our project is called *myproject* and the environment is called *demo*:

You should expect to find a file named `web.yml.sample` in the Git repository used for the stack.

Then, in the config repository used to store the configuration of your project, you might find the following file at the top level: `my-org/my-project/my-env/my-component/ansible/demo-web.yml`


---

# Setup dev env for stacks

This section is comming soon. Right now in few lines to write a new stack we would advice to use stack blueprint feature.


---

# Linking Stacks with Terraform

Sometimes it's useful to establish connections or "links" between different stacks. Let's walk through a simple example using the public [Magento stack](https://github.com/cycloid-community-catalog/stack-magento).

If we examine the Terraform sample file, we'll notice that one of the required arguments is `vpc_id`.

[stack-magento/terraform/magento.tf.sample](https://github.com/cycloid-community-catalog/stack-magento/blob/master/terraform/magento.tf.sample#L11)

stack-magento/terraform/magento.tf.sample

```
module "magento" {
  source    = "module-magento"
  org       = "($ .org $)"
  project   = "($ .project $)"
  env       = "($ .env $)"
  component = "($ .component $)"
  vpc_id    = "<vpc-id>"
}
```

Additionally, the Magento stack exposes several [Terraform outputs](https://www.terraform.io/language/values/outputs) in the [outputs.tf](https://github.com/cycloid-community-catalog/stack-magento/blob/master/terraform/outputs.tf) file.

Each Terraform output is stored in the remote `tfstate` file, as explained in the [Troubleshooting with a manual run of Terraform plan](/reference/stacks/reference/manually-run-terraform.md) section.

Now, let's consider the `vpc_id` parameter. Suppose we have another infrastructure stack dedicated to providing a VPC and exposing its ID as a Terraform output.

We can leverage Terraform's remote state provider to establish a connection between our Magento stack and retrieve the `vpc_id` from the infrastructure stack. You can learn more about remote state data [here](https://www.terraform.io/language/state/remote-state-data).

To create this link, obtain the bucket name (*infrastructure-terraform-remote-state*) and the path (*infrastructure/infra/infrastructure-infra.tfstate*) of the remote `tfstate` file used by the infrastructure stack.

Next, create the following `provider.tf` file:

stack-magento/terraform/provider.tf

```
// Connect this stack to the infra stack to be able to use directly outputs
data "terraform_remote_state" "infrastructure" {
  backend = "s3"

  config {
    bucket = "infrastructure-terraform-remote-state"
    key    = "infrastructure/infra/infrastructure-infra.tfstate"
    region = "${var.aws_region}"
  }
}
```

With this new file, you can utilize outputs from the infrastructure stack as Terraform data in the Magento stack or configuration, like this:

stack-magento/terraform/magento.tf.sample

```
module "magento" {
  source    = "module-magento"
  org       = "($ .org $)"
  project   = "($ .project $)"
  env       = "($ .env $)"
  component = "($ .component $)"
  vpc_id    = "${data.terraform_remote_state.infrastructure.vpc_id}"
...
```


---

# Manual Run of Terraform Code

Sometimes, it could be useful to run Terraform commands manually from a stack's source code, for tasks such as syntax validation. For example:

```
terraform fmt
terraform validate
```

Here are the two steps to follow:

1. Merge the configuration and the stack.
2. Configure Terraform to use the proper remote state storage.
3. Run Terraform.

Let's assume the following information:

* **Stack**: `my-stack`
* **Org canonical**: `my-org`
* **Project canonical**: `my-project`
* **Environment canonical**: `my-env`
* **Component canonical**: `my-env`

### First - Merge the Config and the Stack[​](#first---merge-the-config-and-the-stack "Direct link to First - Merge the Config and the Stack")

Clone the Stack and Config repositories into 2 directories:

```
git clone git@.../mygit.git -b stacks stacks
git clone git@.../mygit.git -b config config
```

Next, create a **merged\_stack** directory where we will merge the stack and the config. To reproduce the usual pipeline task `merge-stack-and-config`, execute the following commands:

```
export STACK=my-stack
export ORG=my-org
export PROJECT=my-project
export ENV=my-env
export COMPONENT=my-component

mkdir -p merged-stack
cd merged-stack

# Copy stack files
rsync -av --delete \
  --exclude=".terraform" \
  --exclude="backend.tmp.tf" \
  --exclude="terraform.tfstate*" \
  ../stack/${STACK}/terraform/ ./

# Copy config files on top
rsync -av ../config/${ORG}/${PROJECT}/${ENV}/${COMPONENT}/terraform ./
```

tip

Please ensure that the paths of the stack and config files match the ones defined in your `.cycloid.yml`.

### Second - Configure Terraform to Use the Proper Remote State Storage[​](#second---configure-terraform-to-use-the-proper-remote-state-storage "Direct link to Second - Configure Terraform to Use the Proper Remote State Storage")

When running Terraform locally, we need to configure it to fetch the remote state file. In a pipeline, this configuration is embedded in the Concourse Terraform resource definition. However, for local Terraform execution, we must manually provide a local configuration.

For projects using the [Cycloid Terraform HTTP remote backend](/reference/inventory/concepts.md#how-to-use-cycloid-http-backend-in-local-terraform-code), follow these steps:

Note

If you are not using the Cycloid Terraform HTTP remote backend, you will need to refer to the pipeline configuration to determine the appropriate Terraform backend and reproduce it accordingly.

Ensure to replace the following placeholders with appropriate values:

* `CYCLOID_API_URL`: Replace this with the Cycloid URL, for example, <https://http-api.cycloid.io> for the Cycloid SaaS version.
* `JWT_TOKEN`: Use the Cycloid HTTP backend token, which can be found under your project configuration tab.

```
export CYCLOID_API_URL="..."
export JWT_TOKEN="..."

echo "terraform {
  backend \"http\" {
    address = \"${CYCLOID_API_URL}/inventory?jwt=${JWT_TOKEN}\"
  }
}
" > backend.tmp.tf
```

### Finally - Run Terraform[​](#finally---run-terraform "Direct link to Finally - Run Terraform")

At this stage, you should be able to execute Terraform.

```
# Run Terraform
terraform init -backend=true
terraform plan
```

Depending on your Terraform code, it may expect input variables to be provided. Let's use our usual input variables as an example:

```
export ORG=my-org
export PROJECT=my-project
export ENV=my-env
export COMPONENT=my-component

cat <<EOF > terraform.tfvars
organization = "${ORG}"
project = "${PROJECT}"
env = "${ENV}"
component = "${COMPONENT}"
EOF
```


---

# Override a Stack with Config at Merge

If you're using a Cycloid stack or one based on a Cycloid template, it should adhere to the [Concept of a Stack](/reference/stacks/concepts/stack-concept.md).

In most of our stacks, the **merge** between the stack and config is managed in the **pipeline**. Refer to the pipeline [merge-stack-and-config example](/reference/ci-cd-pipelines/concepts/cycloid-toolkit.md#stack-concept-with-merge-stack-and-config) for detailed information. Our approach to this merge can be seen as a straightforward copying of config files over the stack's files.

This means you can include whatever you need in either the stack or the config. Just remember that files in the config will override those in the stack. This can be useful in specific scenarios where you want to override certain files from a stack. To achieve this, simply create the same file paths in your config as in the stack.

![Stack Config](/assets/images/stack-config-b6c19cd81362f124f5fbbc03de61e010.png)

### Example: Override a Stack with Config Merge[​](#example-override-a-stack-with-config-merge "Direct link to Example: Override a Stack with Config Merge")

A `stack` is typically designed to align with the `config` and requires a minimal number of files. However, Cycloid doesn't enforce a specific behavior, allowing you to define or override everything with the config.

As an example, let's use the public Magento stack and override a Terraform file, [ami.tf](https://github.com/cycloid-community-catalog/stack-magento/blob/master/terraform/module-magento/ami.tf).

Note, this behavior is not specific to Terraform or overriding files; you can create new files or use them with Ansible as well.

To achieve this, navigate to the config repository and create the same relative path as the stack:

* Path in the stack: `<stack repository>/terraform/module-magento/ami.tf`
* Expected path in config: `<config repository>/<org>/<project>/<env>/<component>/terraform/module-magento/ami.tf`

Here's a sample of the new file `<config repository>/<org>/<project>/<env>/<component>/terraform/module-magento/ami.tf`:

```
data "aws_ami" "debian_jessie" {
  most_recent = false
  filter {
    name   = "name"
    values = ["overrided …. "]
  }
}
```

For more details on the merge process, refer to the `merge-catalog-and-config` task in the pipeline.

note

The path may vary between stacks, as it depends on the pipeline design.

It will always be referenced in the `.cycloid.yml`.


---

# Public and Community Stacks

If you are looking for additional stacks, Cycloid provides a few divided into two categories: Public and Community Stacks.

All of these stack source codes can be found on our GitHub repository: [cycloid-community-catalog](https://github.com/cycloid-community-catalog).

To add new stacks to Cycloid, all you need to do is add the Git URL of a stack in Cycloid as a [catalog repository](/reference/config-and-catalog-repository/.md#quickstart).

## Public Stacks[​](#public-stacks "Direct link to Public Stacks")

Public stacks are a small group of stacks that are easy to use and maintained by Cycloid. You can either define just one of these stacks using the specific GitHub repository, or you can get all of them at once using our virtual Git repository called `public-stacks`.

```
https://github.com/cycloid-community-catalog/public-stacks
```

Public stacks group the following one:

| Stack name                                                                              | Description                                                                                                                                                                                                   |
| --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [dummy](https://github.com/cycloid-community-catalog/stack-dummy)                       | Empty stack reserved for debug and development purpose. This stack just create a dummy pipeline                                                                                                               |
| [ansible-runner](https://github.com/cycloid-community-catalog/stack-ansible-runner)     | Enables you to execute an Ansible playbook. This stack includes a preconfigured pipeline for running a single Ansible playbook                                                                                |
| [terraform-runner](https://github.com/cycloid-community-catalog/stack-terraform-runner) | This stack enables you to execute a Terraform plan and apply it to Terraform code stored in a Git repository.                                                                                                 |
| [dockerbuild](https://github.com/cycloid-community-catalog/stack-dockerbuild)           | This stack facilitates building and running tests on a Docker image before pushing it to a registry.                                                                                                          |
| [getting-started](https://github.com/cycloid-community-catalog/stack-getting-started)   | The purpose of the "Getting Started" stack is to provide an easy-to-use Cycloid stack for users during the onboarding process. This stack offers multi-cloud support for creating a default compute instance. |

## Community stacks[​](#community-stacks "Direct link to Community stacks")

Community stacks are more advanced and complex stacks designed to offer production-ready services. They provide comprehensive solutions for various use cases and scenarios. While they may require a higher level of expertise to configure and deploy.

| Stack name                                                                  | Description                                                                                                                  |
| --------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| [k8s-runner](https://github.com/cycloid-community-catalog/stack-k8s-runner) | This stack is designed to manage resources deployed on a Kubernetes cluster using YAML manifests and/or Terraform resources. |
| [LEMP](https://github.com/cycloid-community-catalog/stack-lemp)             | This stack will create a full LEMP infrastructure based on Auto Scaling Groups (ASG) and an RDS database on AWS              |
| [monitoring](https://github.com/cycloid-community-catalog/stack-monitoring) | This stack provides a way to deploy a monitoring server based on either a specific cloud provider solution or Prometheus.    |
| [compute](https://github.com/cycloid-community-catalog/stack-compute)       | This stack enables the deployment and configuration of a compute instance in one of the available providers.                 |


---

# Special variables

<!-- -->

Variables can be used in any sample files, `.cycloid.yml`, `.forms.yml`, terraform samples, ansible and pipelines. It can also be used by the Custom Technology, in that case, you will also have access to stackforms variables.

To use a variable, follow this format:

```
($ .variable_name $)
```

Here is the list of all the available special variables:

Reminder

Resources `canonicals` is the unique name attributed on a resource.

Resources `names` are the pretty names of a resource displayed on the UI, it can change and is not reliable.

Always use the `canonical` in your code and automations for resources reference.

<!-- -->

| Variables                                       | Description                                                                                                                                                                         |
| ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ```
($ .org $)
```                                | Org canonical.<br />*Aliases: organization, org\_canonical, organization\_canonical*                                                                                                |
| ```
($ .org_name $)
```                           | Org name.<br />*Alias: organization\_name*                                                                                                                                          |
| ```
($ .env $)
```                                | Env canonical.<br />*Aliases: environment, env\_canonical, environment\_canonical*                                                                                                  |
| ```
($ .env_name $)
```                           | Env name.                                                                                                                                                                           |
| ```
($ .component $)
```                          | Component canonical.<br />*Alias: component\_canonical*                                                                                                                             |
| ```
($ .component_name $)
```                     | Component name.                                                                                                                                                                     |
| ```
($ .project $)
```                            | Project canonical.<br />*Alias: project\_canonical*                                                                                                                                 |
| ```
($ .project_name $)
```                       | Project name.                                                                                                                                                                       |
| ```
($ .project_owner $)
```                      | Canonical of the project owner (usuallaly, the user who created the project).<br />*Alias: project\_owner\_canonical*                                                               |
| ```
($ .project_owner_name $)
```                 | Project owner name.                                                                                                                                                                 |
| ```
($ .project_owner_surname $)
```              | Project owner surname.                                                                                                                                                              |
| ```
($ .project_owner_email $)
```                | Project owner email.                                                                                                                                                                |
| ```
($ .catalog_repository $)
```                 | Catalog repository canonical.<br />*Alias: catalog\_repository\_canonical*                                                                                                          |
| ```
($ .catalog_repository_name $)
```            | Catalog repository name.                                                                                                                                                            |
| ```
($ .catalog_repository_url $)
```             | Catalog repository git URL where the stack is located.<br />*example: `git@github.com:cycloidio/...git`*                                                                            |
| ```
($ .catalog_repository_branch $)
```          | The branch of the catalog repository where the stack resides.<br />*example: `stacks`*                                                                                              |
| ```
($ .catalog_repository_credential_type $)
``` | The type of credential used to access the stack's service catalog.<br />*possible values: `basic_auth`, `ssh`*                                                                      |
| ```
($ .catalog_repository_credential_path $)
``` | The path of the credential used for the catalog repository. See the [credential section](/reference/credentials/quickstart.md#create-a-credential) for more details about the path. |
| ```
($ .stack $)
```                              | Stack canonical.<br />*Alias: stack\_canonical*                                                                                                                                     |
| ```
($ .stack_name $)
```                         | Stack name.                                                                                                                                                                         |
| ```
($ .stack_path $)
```                         | The path of the stack in the catalog Git repository, basically the directory where the `.cycloid.yml` file is located.                                                              |
| ```
($ .config_root $)
```                        | Alias to do `($ .org $)/($ .project $)/($ .env $)/($ .component $)` which is our default `destination` config path pattern.                                                         |
| ```
($ .config_repository $)
```                  | Config repository canonical.<br />*Alias: config\_repository\_canonical*                                                                                                            |
| ```
($ .config_repository_name $)
```             | Config repository name.                                                                                                                                                             |
| ```
($ .config_repository_url $)
```              | The URL of the config repository configured for this stack.<br />*example: `git@github.com:cycloidio/...git`.*                                                                      |
| ```
($ .config_repository_branch $)
```           | The branch in the config repo holding the configuration for the stack.<br />*example: `config`.*                                                                                    |
| ```
($ .config_repository_credential_type $)
```  | The type of credential used to access the stack's config repo.<br />*possible values: `basic_auth`, `ssh`*                                                                          |
| ```
($ .config_repository_credential_path $)
```  | The path of the credential used for the config repository. See the [credential section](/reference/credentials/quickstart.md#create-a-credential) for more details about the path.  |
| ```
($ .inventory_jwt $)
```                      | The JSON Web Token used to access the inventory. See the [inventory usage](/reference/inventory/concepts.md#how-to-use-it-in-a-pipelines-) section for more information.            |
| ```
($ .api_url $)
```                            | The URL of the Cycloid API.<br />\*example: `https://http-api.cycloid.io`.                                                                                                          |
| ```
($ .console_url $)
```                        | The URL of the Cycloid console.<br />\*example: `https://console.cycloid.io`.                                                                                                       |
| ```
($ .use_case $)
```                           | The use case name of the stack. See the [Use cases](/reference/stacks/concepts/use-cases.md) concept for more informations.                                                         |


---

# Upgrade Terraform code

This tutorial gives you some tips on how to upgrade the Terraform used in cycloid's stacks, to the latest version (at the moment of writing terraform v1).

If you have any doubts don't hesitate to [contact us](mailto:support@cycloid.io) :)

### How to upgrade using Cycloid?[​](#how-to-upgrade-using-cycloid "Direct link to How to upgrade using Cycloid?")

#

Upgrading a stack's terraform in Cycloid consists of 2 steps:

* Upgrading the **terraform version of the terraform concourse resource**, that is used in the pipeline. You can check the available resource versions on the [resource dockerhub](https://hub.docker.com/r/ljfranklin/terraform-resource/tags). The value is defined in the concourse file that defines the pipeline in the `resource_types` section, as follows:

  ```
   resource_types:
      - name: terraform
      type: registry-image
      source:
          repository: ljfranklin/terraform-resource
          tag: ${terraform_version}
  ```

  * You can change the value either by:

    <!-- -->

    * **editing the running pipeline directly** on the cycloid dashboard. Not recommended since this doesn't change the pipeline variables stored and thus the value is not stored;
    * or by **editing the pipeline variables file and refresh the pipeline**. This file is located in the config repository on the `pipeline/` folder and you should change the `terraform_version` variable.

  * For more info regarding this step please refer to the [pipeline section](/reference/ci-cd-pipelines/concepts/pipelines-overview.md) in our docs.

* Upgrading the **terraform version on the code**, usually stored in the folder `terraform/` in the stack branch. Performing this task will vary according to the stack's current terraform version, the version to upgrade to and the terraform code itself.

* To check the current version you can look into the `versions.yml` file. Please refer to the next sections depending on the version of your stack to see some tips on how to validate the upgrade using the cycloid dashboard.<br />

#### Terraform 0.13 and later[​](#terraform-013-and-later "Direct link to Terraform 0.13 and later")

For Terraform 0.13 and later upgrading can be somewhat easy since there are no changes in the tfstate.

You just need to update the stack's terraform code version and when you have the new code version commited into the stack/ git branch just relaunch the pipeline job `terraform plan`, without forgeting that it should match the pipeline's terraform resource version has specified above.

If it passes with no errors for that version upgrade, then you just need to lauch `terraform apply` to have the upgrade for that tf version finished.

**Beware** if you're changing in a production pipeline, to **check if the terraform plan results in no changes** on the resources since this can impact your service.

For tips on how to upgrade terraform code please check the [procedure to upgrade TF locally](#procedure-to-upgrade-locally) section of this documentation.

#### Terraform <=0.12[​](#terraform-012 "Direct link to Terraform <=0.12")

For Terraform 0.12 and bellow upgrading the terraform may require in addition of changing the code, to change the tfstate as well. So after you finished with the terraform code update and you commited it into the stack/ git just relaunch the pipeline job `terraform plan`, without forgeting that it should match the pipeline's terraform resource version has specified above.

If you encountered some errors please check the section of this documentation [known errors](#known-errors) which can give you some tips on how to solve some errors that you may encounter.

If on the other hand you didn't found any error during apply, then you just need to lauch `terraform apply` to have the upgrade for that tf version finished.

**Beware** if you're changing in a production pipeline, to **check if the terraform plan results in no changes** on the resources since this can impact your service.

For tips on how to upgrade terraform code please check the [upgrade TF locally](#procedure-to-upgrade-locally) section of this documentation.

### Known errors[​](#known-errors "Direct link to Known errors")

* Performing an upgrade from **0.12 to 0.13** requires some changes in tfstate. In fact if you change both the pipeline's terraform resource version and the terraform code version, you may encounter an error relating to the providers format in the tfstate, similar to as follows:

  ```
  - Failed to instantiate provider "registry.terraform.io/-/aws" to obtain schema: unknown provider "registry.terraform.io/-/aws"
  - Failed to instantiate provider "registry.terraform.io/-/random" to obtain schema: unknown provider "registry.terraform.io/-/random"
  ```

  * To solve this issue, you have to edit the tfstate stored in the remote bucket.You can dot this by editing:

    * **Manually**: by changing the providers that resulted in the bug in the yaml as follow:<br />

      ```
       --- "provider": "provider[\"registry.terraform.io/-/aws\"]"
       +++ "provider": "provider[\"registry.terraform.io/hashicorp/aws\"]"
      ```

    * **With terraform command**: `terraform state replace-provider` that is used to replace the provider in the tfstate. This will change the selected tfstate file and create a copy of the original version. Here follows an example command:

      ```
      terraform state replace-provider -state=/$PATH_TO_TFSTATE/tfstate.json -- -/aws registry.terraform.io/hashicorp/aws
      ```

  * After editing, you need to upload the changed file back to the bucket and relaunch the `terraform plan` job on the pipeline. **Tip!** Make sure that the upload tfstate has the same name has the remote stored one, since depending on your provider it migth be dowloaded with a different name.

### Procedure to upgrade locally[​](#procedure-to-upgrade-locally "Direct link to Procedure to upgrade locally")

This section details a local procedure on how to upgrade the terraform code.

We'll use our [stack prometheus](https://github.com/cycloid-community-catalog/stack-prometheus) has an example of the files to change.

1. Install [terraform manager](https://github.com/tfutils/tfenv#installation) - to allow to easily switch between terraform versions easily

2. Check the **current version of the stack terraform**. You can do this:

   * by checking in the **cycloid console** the tfstate of the pipeline to upgrade in the last succeffull terraform-apply job

   * OR by checking the **terraform resource tag** used in the concourse pipeline:

   ```
   grep -A1 'repository: ljfranklin/terraform-resource' pipeline/pipeline.yml
   ```

3. Install and use the next minoir terraform version using the terraform manager:

   ```
   tfenv install $VERSION
   tfenv use $VERSION
   ```

   * **Tip!** to list all versions available you can run: `tfenv list-remote`

4. **Test locally** for changes in terraform code. For that you can change the terraform version in [terraform/versions.tf](https://github.com/cycloid-community-catalog/stack-prometheus/blob/master/terraform/versions.tf#L3). Some of the useful commands you may need.

   ```
   terraform init
   terraform ${TF_version}upgrade (if available)
   terraform validate
   terraform fmt
   ```

5. **Test remotely** for changes/bugs using cycloid console. For that:

   * start by changing the terraform resource tag in [pipeline/pipeline.yml](https://github.com/cycloid-community-catalog/stack-prometheus/blob/master/pipeline/pipeline.yml#L52) and commit the changes

   * then on the pipeline check the state of the job terraform plan

   * finally launch terraform apply job

   * **Tip!** to get more verbose on the the terraform jobs results you can add the [TF\_LOG](https://www.terraform.io/internals/debugging) environment variable in the terraform resource in the pipeline. Jus edit the pipeline and add the following env variable in the tfstate resource in the section resources, as follows:

     ```
         - name: tfstate
             type: terraform
             (...)
             env:
                 TF_LOG: DEBUG
     ```

6. **Repeat steps 3 to 5**, for each minor version until arriving at the desired version.<br />Example upgrade order: 0.12 → 0.13 → 0.14 → 1.0

::: tip Note! For more details regarding how to upgrade terraform code please check the [terraform official docs](https://www.terraform.io/language/upgrade-guides) and the [terraform changelog](https://github.com/hashicorp/terraform/blob/main/CHANGELOG.md) for more details. :::


---