As described in concepts of stack, a stacks in Cycloid is stored in a git repository. From a technical point of view for a stack to be valid in Cycloid you have to define and create a .cycloid.yml into your git repository.

This file will contain the name, description, keyword, and few other metadata which define your stack. Read more about .cycloid.yml file format.

# StackForms

To configure your stack via a user-friendly form, you'll need to create a new file at the same location as your .cycloid.yml file. This file will be .forms.yml

If present, Editor view for project configuration will be replaced by StackForms, which takes a more visual approach, using widgets, hints, dropdowns, etc. Please note that when you're using StackForms, only a subset of elements might be configurable (depending on what was defined in the file) and that StackForms cannot be used to edit the pipeline (only the variables).

forms-create

# Private stack structure

A private stack is defined by at least one .cycloid.yml file and one Pipeline. Those files have to be put in a git repository which can be private or public.

To store the config of all your private stacks we usually use the same git repository with a dedicated branch named config. You can, however, provide a dedicated git repository for each config.

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.

So, in the end, for private stacks you need to create a git repository containing a "config" branch to store the configuration files and a secondary "stacks" branch to store the stacks.

git clone -b <config> git@github.com:<repository name>.git <config>
git clone -b <stacks> git@github.com:<repository name>.git <stacks>
1
2

In the stacks branch you should find at the top level the names of stacks. For example stack-infrastructure, stack-myApp, ...

In those stacks, you might have 3 directories and 2 files:

Here is an example :

stack-myApp/.cycloid.yml
stack-myApp/.forms.yml
stack-myApp/pipeline/pipeline.yml
stack-myApp/pipeline/variables.sample.yml
stack-myApp/terraform/provider.tf
stack-myApp/ansible/site.yml
1
2
3
4
5
6

In the config branch you might find at top level name of stacks. For example infrastructure, myProject, ...

  • Terraform: The call of the module defined in the stack. The call contains all configuration variable of the module. You can imagine stack like a function definition and config like a call of that function specifying args.
  • Ansible: Contains usually variable file used by the playbook defined in the stack.

Here is an example :

myProject/terraform/prod/variables.tf
myProject/ansible/prod-variables.yml
1
2

# Creating and updating a catalog repository

As Creating and updating a config repository, creating or updating the catalog repository is also a pretty easy task.

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.

NOTE

If you manually add or remove a stack in the git repository of your stack, or if you do any changes in a .cycloid.yml file, a refresh of the stack is required.

To do so :

  1. Go on your catalog-repositories page.
  2. Then hit the Refresh this repository button on your private catalog repositories.

Read more about .cycloid.yml file here.

# Credentials configuration

A private stack is located under a git repository. To access this repository you will first need to add a new SSH credential to access it. You can do it from Cycloid credentials manager.

To do so, go to the security/credentials page using the main navigation. From there you can either select an existing credential or create a new one, but make sure to use the SSH or basic_auth credential type.

Add Git Credential

How to use Github access token

Following the documentation, Github access token (opens new window) can be used as basic_auth credential.

  1. First create a basic_auth credential, set your Github username as username and the Github generated token as password.
  2. Then you will be able to create or update your catalog-repositories and config-repositories with this new basic_auth credential.

Then go to the Catalog repositories icon Manage Organizations in the main navigation to start creating a new one using the previously added SSH credential.

# Catalog repository configuration

Click on the Add private catalog button to access the catalog repository creation form:

Add Private Catalog Repository button

From here, you'll only need to add four information:

  • A name for your catalog repository
  • The git URL in ssh format of your catalog repository (i.e. git@github.com:demonstration/my-catalog.git)
  • A previously created credential (see Credentials)
  • The branch of your choice which will contain all the stacks

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.

Create a Catalog Repository

To update a catalog repository you can go the catalog repository list page and click on the one you want to edit.

# Tips and tricks

As described in Concept of a stack, during a deployment, the stack and the config are merged. That means you can put whatever you want in the stack or in the config, keeping in mind that the file in config will override the one located in stack. There is no limit, in some specific cases you can even override an entire stack with config if you respect the same files path.

Stack Config

So, all things required in the config are usually defined by the stack. You can create a stack which does not require any config, or you can create a stack which requires a lot of variables, template, files etc. from the config.