k8comp Docs

User guide

K8comp args

The arguments passed to k8comp are used to find the deployment templates and query hiera.

K8comp uses a files structure to organise all the deployment files.

An explanation can be also found by executing k8comp –help

project

The project k8comp argument is used to locate deployment files in the projects folder and to query hiera. The argument aliases are:

A project can have a single or multiple files. Each project can contain multiple applications which will be deployed individually. This structure comes handy where multiple projects will use have applications named similarly (e.g: api, cache…)

Example:
Below command will deploy the application andromeda nested on galaxies project

k8comp -p galaxies -a andromeda -e development

Below command will deploy only the file called ‘galaxies.yaml|json|yml’ from the projects/galaxies/ folder. No applications will be deployed part of this deployment.

k8comp -p galaxies -e development

Below command will deploy all the files of the project galaxies stored in the folder projects/galaxies/. None of the applications will be deployed part of this deployment.

k8comp -a galaxies -e development

application

The application k8comp argument is used to locate deployment files in the projects folder and to query hiera. The argument aliases are:

An application can be part of a project or can be on it’s own having the files stored in the projects top level.
A k8comp command issues without a project argument will only check deployments in the projects top level.

Example:
Below command will deploy the application andromeda nested in galaxies project

k8comp -p galaxies -a andromeda -e development

Below command will deploy the application andromeda stored in the projects folder top level

k8comp -a andromeda -e development

Below command will deploy all the files of the project galaxies stored in the folder projects/galaxies/. None of the applications will be deployed part of this deployment.

k8comp -a galaxies -e development

Deploy only a specific file, in below example only the service file. Please note that a file with the name service.yaml|json|yml needs to be available within the application folder

k8comp -a andromeda/service -e development

environment

The environment k8comp argument is used only to query hiera. The argument aliases are:

Example:
For the below command to work the hieradata files structure needs to contain a file in hieradata/apps/galaxies/andromeda/development.yaml or hieradata/apps/galaxies/andromeda.yaml or hieradata/apps/galaxies.yaml or hieradata/common.yaml with the variables of the templates from projects/galaxies/andromeda/. Hiera will retrieve the variables based on the hiera.yaml configuration.

k8comp -p galaxies -a andromeda -e development

For the below command to work the hieradata files structure needs to contain a file in hieradata/apps/andromeda/development.yaml or hieradata/apps/andromeda.yaml or hieradata/common.yaml with the variables of the templates from projects/andromeda/. Hiera will retrieve the variables based on the hiera.yaml configuration.

k8comp -a andromeda -e development

location

The location k8comp argument is used only to query hiera. The argument aliases are:

The location argument can be used to enhance the hiera structure.

template

The template k8comp argument it’s only used to locate deployment files in the projects/_templates/ folder. The argument aliases are:

The template argument can be used to deploy components which needs to be part of different applications.

Example:
Below command will use a template from projects/_templates/healthcheck and use the hiera variables from andromeda application.

k8comp -t healthcheck -a andromeda -e development

xtra

The xtra k8comp argument it’s used to overwrite any variables values. The argument aliases are:

Example:
If the variable value for the healthcheck_tag is in hiera 3001, below command will overwrite that value with 4009.

k8comp -t healthcheck -a andromeda -e development -x healthcheck_tag=4009

Multiple xtra arguments can be used at a time

branch

Dependencies

Recommended options

The only way of using the branch feature is in conjunction with k8comp_environments set to enabled.
If projects_repo and/or hieradata_repo are set k8comp can create the correct paths for the projects/hieradata.

The projects and hieradata are expected to be in projects/environments/branch/

The default branch is master. To customise the branch change main_deployment_branch in k8comp.conf

The branch k8comp argument it’s only used to set the path to the deployment files. The argument aliases are:

There are two setup options for k8comp_environments feature:

k8comp pull can create the structure automatically if the user which executes k8comp commands has ssh git access

Example

k8comp -p galaxies -a andromeda -e development -b development

Single repo

The single repository option requires that both projects and hieradata to be in the same repository. An example can be found here.

If the user which runs k8comp has access to the repos via ssh the repository can be configured on the projects_repo. K8comp will create automatically the folders structure when k8comp pull command is executed.

Multi repo

The multi repository option requires that the projects and hieradata to have dedicated repositories. The files should be saved in the root level. Examples for projects repository and hieradata

pull & auto pull

Dependencies

The pull k8comp argument cannot be used as part of a deployment. The argument aliases are:

Example:
Pull the main_deployment_branch

k8comp pull

Pull a specific branch

k8comp pull -b development

If auto_git_pull is set to true on every deployment k8comp will pull the specified branch/main_deployment_branch

k8comp -a andromeda -e development -b development

helm

Helm argument is used to create a helm chart. K8comp needs to be properly configured in order to have this working.
The flag is automatically selected as part of the k8comp helm plugin.

To create a helm chart using k8comp first install the k8comp plugin for helm. Once completed execute the k8comp command prefixed by helm. The command will create a helm chart in ‘pwd’ and push that package to a repository (if available).
To deploy the chart the usual helm commands can be used.

The helm chart will be named based on the k8comp command. If the compile is successful there will be a notification message with the name of the application.

Example:

helm k8comp -p galaxies -a andromeda -e development

helm-package-version

The argument can be only used in conjunction with helm argument and it’s used to specify a helm chart version of a specific application.
By default the helm deployment will have as a version Year.MonthDay.HourMinuteSeconds.
To overwrite this behaviour specify the –helm-package-version in the build command.

Example:

helm k8comp -p galaxies -a andromeda -e development --helm-package-version 3.1.2

AWS Secrets Manager

k8comp can pull secrets from AWS Secrets Manager. Locally awscli tool will need to be installed. If the deployment is done from an instance which can assume a role there is no need to provide any credentials. For the awscli configuration please check the official AWS documentation.

The variables can be from the main template file or from hieradata.

The variable prefix default is AWSSM and can be set as part of the config with aws_sm_prefix.

Hieradata variable to retrieve a single value from the main secret in base64 format

AWSS(BASE64,secretName:singleVariable)

Hieradata variable to retrieve a single value from the main secret in plain text

AWSS(secretName:singleVariable)

Hieradata variable to retrieve the full secret in base64 format

AWSS(BASE64,secretName)

To set a default variable in the main deployment files use %{} for the secret like on the below examples

%{AWSS(secretName:singleVariable)}
%{AWSS(BASE64,secretName:singleVariable)}

Currently multiline AWS secrets variables in plain text are not supported