Commit 00fedbd2 authored by Thomas Boni's avatar Thomas Boni
Browse files

add documentation

parent fd7130b1
Loading
Loading
Loading
Loading
+1 −1
Original line number Diff line number Diff line
@@ -4,4 +4,4 @@ stages:

include:
  # Go2Scale DevSecOps
  - remote: https://gitlab.com/go2scale/jobs/raw/2020-03-05_1/jobs/documentation.gitlab-ci.yml
  - remote: https://gitlab.com/go2scale/jobs/raw/2020-03-05_2/jobs/documentation.gitlab-ci.yml

docs/about.md

0 → 100644
+3 −0
Original line number Diff line number Diff line
# About us

https://go2scale.com

docs/contributing.md

0 → 100644
+1 −0
Original line number Diff line number Diff line
🚧 *Work in progress*
+144 −0
Original line number Diff line number Diff line
# Go2Scale DevSecOps templates
# Getting started

Go2Scale DevSecOps CI & CD jobs & pipelines templates repository

* [Description](#description)
* [Getting started](#getting-started)
    * [Global configuration](#global-configuration)
        * [Optional configuration](#optional-configuration)
    * [Pipeline templates](#pipeline-templates)
    * [Jobs templates](#jobs-templates)
* [Pipeline](#pipeline)
    * [Kubernetes](#kubernetes)
* [Jobs](#jobs)
    * [Quality](#quality)
    * [Build](#build)
    * [Helm](#helm)

## Description

[Jobs repository](https://gitlab.com/go2scale/jobs) contains all Go2Scale
DevSecOps CI & CD jobs & pipelines templates. This documentation goal is to
explain how to use them efficiently and easilly in your projects.

We offer 2 levels of modules:

**Pipeline** templates: multiple jobs assembled in a workflow

* Easy to use, just import the template in your CI configuration
* Must be consitent with your software and deployment type
* Customizable through configuration

**Jobs** templates: only one jobs

* Can be used unitary or to create fully customs pipelines
* Adaptable to any kind of software and deployment type
* Customizable through configuration

## Getting started

### Global configuration
## Global configuration

In your Gitlab 🦊 project, your configuration is defined in `.gitlab-ci.yml`
file. If it doesn't exist, create it.
@@ -50,7 +13,7 @@ of `.gitlab-ci.yml`:

Example of declaration in `.gitlab-ci.yml` file:

```
``` yaml
variables:
  # Go2Scale global variables
  BOT_USER_ID: '5097980'
@@ -64,7 +27,7 @@ in project (or supergroup) CI/CD settings:
* `DOCKER_AUTH_CONFIG`: docker auth configuration (*given by Go2Scale*) to access images
* `BOT_TOKEN`: secret token of bot user to interact with Gitlab API

#### Optional configuration
### Optional configuration

If you want to use custom template repo with a restricted access add
these variables. Note that **SECRET** variables must be declared in
@@ -73,7 +36,7 @@ CI/CD settings and never in clear text in `.gitlab-ci.yml`:
* `TEMPLATES_REPO_USER`: user name to with at least read access to repository
* **SECRET** `TEMPLATES_REPO_PASSWORD`: password (or token) with at least read access to templates repository

### Pipeline templates
## Pipeline templates

First of all, you have to find for a pipeline template matching with your
project in [Pipelines list](#pipelines).
@@ -81,27 +44,27 @@ project in [Pipelines list](#pipelines).
Once selected, you just have to include it. Example of usage of [kubernetes
pipeline template](#kubernetes) in `.gitlab-ci.yml`:

```
``` yaml
include:
  - remote: 'https://gitlab.com/go2scale/jobs/raw/2020-02-29_1/pipelines/kubernetes.gitlab-ci.yml'
  - remote: 'https://gitlab.com/go2scale/jobs/raw/2020-03-05_1/pipelines/kubernetes.gitlab-ci.yml'
```

Note that `2020-02-29_1` in url is the versioning `tag` in jobs repository
Note that `2020-03-05_1` in url is the versioning `tag` in jobs repository
used to set the version to use, if you want to use latest version at each run,
you can use `master` instead of this `tag`.

### Job templates
## Job templates

Jobs template usage is simillar to pipeline. Select job(s) you want to use in
[Jobs list](#jobs) and include them in `.gitlab-ci.yml`:

```
``` yaml
include:
  - remote: 'https://gitlab.com/go2scale/jobs/raw/2020-02-29_1/jobs/quality_check.gitlab-ci.yml'
  - remote: 'https://gitlab.com/go2scale/jobs/raw/2020-02-29_1/jobs/helm.gitlab-ci.yml'
  - remote: 'https://gitlab.com/go2scale/jobs/raw/2020-03-05_1/jobs/quality_check.gitlab-ci.yml'
  - remote: 'https://gitlab.com/go2scale/jobs/raw/2020-03-05_1/jobs/helm.gitlab-ci.yml'
```

### Full example
## Full example

Of course, you can combine pipelines templates, jobs templates and your
own jobs.
@@ -109,7 +72,7 @@ own jobs.
An example of a full `.gitlab-ci.yml` file with [kubernetes pipeline
template](#kubernetes), 2 jobs templates and a custom `unit_tests` template:

```
``` yaml
variables:
  # Go2Scale global variables
  BOT_USER_ID: '5097980'
@@ -119,9 +82,9 @@ variables:

include:
  # Go2Scale DevSecOps
  - remote: 'https://gitlab.com/go2scale/jobs/raw/2020-02-29_1/pipelines/kubernetes.gitlab-ci.yml'
  - remote: 'https://gitlab.com/go2scale/jobs/raw/2020-02-29_1/jobs/terraform.gitlab-ci.yml'
  - remote: 'https://gitlab.com/go2scale/jobs/raw/2020-02-29_1/jobs/load.gitlab-ci.yml'
  - remote: 'https://gitlab.com/go2scale/jobs/raw/2020-03-05_1/pipelines/kubernetes.gitlab-ci.yml'
  - remote: 'https://gitlab.com/go2scale/jobs/raw/2020-03-05_1/jobs/terraform.gitlab-ci.yml'
  - remote: 'https://gitlab.com/go2scale/jobs/raw/2020-03-05_1/jobs/load.gitlab-ci.yml'

unit_tests:
  image: python:3.7-alpine3.10
@@ -138,7 +101,7 @@ unit_tests:
An example of a full `.gitlab-ci.yml` file with 2 jobs templates and a custom
`unit_tests` template:

```
``` yaml
variables:
  DOCKER_DRIVER: overlay2
  DOCKER_TLS_CERTDIR: ""
@@ -158,8 +121,8 @@ stages:

include:
  # Go2Scale DevSecOps
  - remote: 'https://gitlab.com/go2scale/jobs/raw/2020-02-29_1/jobs/quality_check.gitlab-ci.yml'
  - remote: 'https://gitlab.com/go2scale/jobs/raw/2020-02-29_1/jobs/helm.gitlab-ci.yml'
  - remote: 'https://gitlab.com/go2scale/jobs/raw/2020-03-05_1/jobs/quality_check.gitlab-ci.yml'
  - remote: 'https://gitlab.com/go2scale/jobs/raw/2020-03-05_1/jobs/helm.gitlab-ci.yml'

code_quality:
  QUALITY_SEVERITY_LEVEL: 'MAJOR'
@@ -175,96 +138,7 @@ unit_tests:
    - make test
```

Note:
!!! note
    * `code_quality` variable section is specified to customize its behavior
    * because we don't use a pipeline template, we have to declare stages list
## Pipelines

### Kubernetes

Build project as Docker image and deploy it on Kubernetes using Helm.

#### Specifications
* File: https://gitlab.com/go2scale/jobs/raw/<TAG>/pipelines/kubernetes.gitlab-ci.yml
* Integration
  * [quality check](#quality)
  * [build](#build)
* Deployment
  * [helm](#helm)

## Jobs

### 🔍 Quality

Auto-detect file in repo and run all [coala](https://coala.io) relevant linters on it.

#### How to use it

* Variables:
  * **TODO:** put variables from https://gitlab.com/go2scale/dockerfiles/quality-check here

#### Specifications

* File: https://gitlab.com/go2scale/jobs/raw/TAG/jobs/quality_check.gitlab-ci.yml
* Publications:
  * Full report as artifact
  * Short report in merge request and job logs
* Image:
  * Repository: https://gitlab.com/go2scale/dockerfiles/quality-check
  * Documentation: https://go2scale.gitlab.io/dockerfiles/quality-check

### 📗 Documentation

Build HTML documentation form Markdown source and deploy it on Gitlab pages

* Build is done in all pipeline, exposed as artifact
* Publication on page is done only on master branch

#### Specifications

* File: https://gitlab.com/go2scale/jobs/raw/TAG/jobs/documentation.gitlab-ci.yml
* Publications in MR: `Documentation` artifact
* Image:
  * Repository: https://hub.docker.com/r/squidfunk/mkdocs-material

#### How to use it

* Variables:
  * `DOCUMENTATION_DISABLE`: disable build ans publication
  * `PAGES_DISABLE`: disable publication on stage

### 📥 Build

*Work in progress...*

### 🚀 Helm

Deploy on your kubernetes cluster using Helm charts.

* In issue branch: review environment
* In master branch: staging environment
* In master branch: production environment (manual)

#### Specifications

* File: https://gitlab.com/go2scale/jobs/raw/TAG/jobs/helm.gitlab-ci.yml
* Publications: *TODO*
* Image:
  * Repository: https://gitlab.com/go2scale/dockerfiles/helm
  * Documentation: https://go2scale.gitlab.io/dockerfiles/helm

#### How to use it

* Chart and values files must be in repo, see Variables section
* Use [helm secrets](https://github.com/futuresimple/helm-secrets) to encrypt/decrypt secrets values files
* Values files must be named like `<ENV>.yaml` for clear text and `secrets.<ENV>.yaml` for encrypted
* Variables:
  * `REVIEW_DISABLE`: disable review deployment
  * `STAGING_DISABLE`: disable staging deployment
  * `PRODUCTION_DISABLE`: disable production deployment
  * `CHART_PATH`: path of helm chart to use. Default: `/charts/$CI_PROJECT_NAME`
  * `VALUES_PATH`: path of values files to use. Default: `./conf/values`
* Secret variables:
  * `PGP_PUBLIC`: public PGP key to decrypt secrets values. Use `file` type.
  * `PGP_PRIVATE`: private PGP key to decrypt secrets values. Use `file` type.
+19 −0
Original line number Diff line number Diff line
<?xml version="1.0" encoding="utf-8"?>
<!-- Generator: Adobe Illustrator 15.1.0, SVG Export Plug-In . SVG Version: 6.00 Build 0)  -->
<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
<svg version="1.1" id="Calque_1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" x="0px" y="0px"
	 width="32px" height="32px" viewBox="0 0 32 32" enable-background="new 0 0 32 32" xml:space="preserve">
<circle fill="#D9D9D9" cx="16.434" cy="8.458" r="0.912"/>
<circle fill="#D9D9D9" cx="24.019" cy="16.158" r="0.913"/>
<path fill="none" stroke="#010202" stroke-width="0.0393" stroke-miterlimit="10" d="M17.192,19.887"/>
<circle fill="#D9D9D9" cx="8.525" cy="15.715" r="0.912"/>
<path fill="#FFFFFF" d="M31.912,17.086c0,6.652-5.249,7.539-5.249,7.539h-7.807v2.176c0.862,0.323,1.478,1.153,1.478,2.128
	c0,1.256-1.018,2.273-2.273,2.273c-1.257,0-2.274-1.018-2.274-2.273c0-0.948,0.582-1.76,1.406-2.102v-6.056l5.147-2.946
	c0.433,0.436,1.03,0.708,1.691,0.708c1.311,0,2.375-1.063,2.375-2.375s-1.064-2.375-2.375-2.375c-1.312,0-2.375,1.063-2.375,2.375
	c0,0.052,0.005,0.104,0.008,0.157l-4.478,2.537v-8.157h-0.03c0.922-0.327,1.581-1.203,1.581-2.236c0-1.312-1.063-2.375-2.374-2.375
	c-1.312,0-2.374,1.063-2.374,2.375c0,1.033,0.66,1.909,1.581,2.236H15.54v8.159l-4.667-2.609c0.041-0.175,0.064-0.356,0.064-0.544
	c0-1.312-1.063-2.375-2.374-2.375c-1.311,0-2.375,1.063-2.375,2.375c0,1.311,1.063,2.375,2.375,2.375
	c0.568,0,1.089-0.201,1.498-0.532l5.479,3.197v3.863H6.563c0,0-6.453-1.166-6.453-7.517c0-6.352,7.954-9.11,7.954-9.11
	s1.375-6.9,8.397-6.9c7.022,0,7.802,6.9,7.802,6.9S31.912,10.433,31.912,17.086z M18.028,28.076c-0.505,0-0.912,0.408-0.912,0.911
	c0,0.506,0.407,0.913,0.912,0.913c0.504,0,0.912-0.407,0.912-0.913C18.94,28.484,18.532,28.076,18.028,28.076z"/>
</svg>
Loading