# Concept of "Stack"

A stack is composed by a stack part and a config part (see Concept of a stack).

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.

Our app is designed to easily mange the stacks content and configuration files through the Catalog Repository and Config Repository pages, with only need of providing SSH credentials and repository URLs.

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 Stacks page
  2. Click on your private stack.
  3. Then hit the Refresh this repository button.

Read more about .cycloid.yml file here.

# Private stack structure

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

# Credentials configuration

Go to the Cycloid dashboards' organization management view and select the organization you want to manage:

Manage Organizations

A private stack is basically a container for stacks and their config that's all stored in a private 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, in the app go to the Credentials page using the main navigation. From there you can either select an existing credential or create a new one - just be sure to use a credential type SSH.

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

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 a file:

  • Terraform: Contains terraform module definition (Terraform Modules), required variables and output of the stack.
  • Ansible: Default variables, roles and ansible playbook to use.
  • Pipeline: Template of the pipeline used only once at the project creation step. Concourse Triggers Docs
  • .cycloid.yml: A file containing the description and the configuration of the stack in the catalog Format of .cycloid.yml file.

Here is an example :

stack-myApp/.cycloid.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

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

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.

# Creating and updating a config repository

Creating or updating the config repository from inside the app 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

From here, you'll need to add five information:

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

Having a config repository as default means having it pre-selected by default during project creation.

Create a Config Repository

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

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

For first, navigate to the catalog repository list page, then 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

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.

# Private stack on AWS

We usually create a CodeCommit repository with a branch stacks containing one or more private stack definition, and a config branch containing all stacks configuration for each environments.

To access to a CodeCommit repository you need to have an Amazon user on which you add a policy to access to CodeCommit and provide a public ssh key. See AWS Access Control Docs

To get the login for your user to clone a CodeCommit repository go to the Amazon console: AWS Console Users

Click on your user and go in the security credentials section, you should find the id under the CodeCommit section.

The first step is to get locally the git repository of the stack and the config with the CodeCommit user id.

git clone -b stack ssh://<userID>@git-codecommit.eu-central-1.amazonaws.com/v1/repos/<name_of_my_service_catalog> stacks
git clone -b config ssh://<userID>@git-codecommit.eu-central-1.amazonaws.com/v1/repos/<name_of_my_service_catalog> config
1
2