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.

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.

For further details on these main points, refer to the following sections.

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

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
• Terraform: Used to create and maintain a target infrastructure on any cloud providers. Contains Terraform module definition (Terraform 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 and user-defined variables configured via StackForm.
• .cycloid.yml: File containing the name, description and the configuration of the stack in the catalog. Format reference.
• 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 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

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:

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 to generate file for any usage (for example, Kubernetes) that can be populated with stack form values and project-specific settings.

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

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

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

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

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.

Stack versioning

A version of a stack is a specific state of the stack's codebase, associated with a Git tag or branch. Versioning allows you to manage changes to the stack over time, enabling users to upgrade or downgrade their components as needed.

Stack versioning is detailed in the Stack versioning documentation.