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"

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.

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

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 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.

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?

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 pipeline: Typically, two files named pipeline.yml and variables.sample.yml. The pipeline is based on the open-source Concourse CI engine and describes which tools to use and how to use them. It's a generic description of the workflow.

Most of our stacks rely on open-source technologies such as:

Technologies	Description
	Stores application and IaC source code
	Describes the infrastructure and services
	Deploys and configures applications inside the target
	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?

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 for more details.

2. Create from Scratch: Build a new stack from scratch using the blueprint feature, 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. This feature enables you to import infrastructure configurations and settings into a new stack effortlessly.

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.

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.

Quickstart

If you are a stack user, we recommend starting by following the getting started: how to use a stack 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, or if you're already an advanced user, you can create a stack from scratch using blueprint feature.