Aziona CLI Documentation
========================

|image0|

|image1| |image2|

.. figure:: https://img.shields.io/badge/-Python-fff?&logo=python
   :alt: Python

   Python

Aziona CLI is a cross CI platform tool that enables the building,
testing, releasing, and deploying, DevOps/GitOps process steps.
Pipelines have two major problems, namely the setup of the environment
with all the dependencies, environmental variables and the management
and maintenance of scripts to be executed during the CI/CD process.
Aziona CLI tries to simplify the aforementioned aspects by allowing
developers to create agnostic and platform-independent configurations.
The advantage of Aziona configurations is that you can declare in one or
more YML / Json files the tasks, environment variables, and dependencies
needed to run the pipeline.

.. figure:: https://raw.githubusercontent.com/azionaventures/aziona-cli/main/docs/images/aziona_process.png
   :alt: File

   File

Architecture
------------

Aziona CLI is written in Python3 and can be used in various ways in both
local and pipelined environments, such as a:

-  Container image (Ubuntu 20.04)
-  Python package
-  GitHub action

**YML structure**

The YML structure is divided into targets that include multiple stages;
on top of that, you can inject a custom environment and additional
settings. Each stage is defined as a single action that imports modules
executed with optional arguments.

.. figure:: https://raw.githubusercontent.com/azionaventures/aziona-cli/main/docs/images/aziona_file.png
   :alt: File

   File

**Modules** Modules are actions executed by a stage; they have different
types like Python or bash modules. Each module has to have defined the
type, module, and eventually additional arguments.

Develop environment
-------------------

**Requirements**

-  python >= 3.6
-  pip3
-  docker and docker-compose

**Setup**

::

   git clone https://github.com/azionaventures/aziona-cli.git
   sudo make setup-dev
   source ./venv/bin/active

Local environment
-----------------

**Requirements**

-  python >= 3.6
-  pip3
-  docker and docker-compose

**Setup**

::

   pip3 install aziona

   # or

   pip3 install aziona==VERSION

Usage
-----

**Ex. Release docker image into Aws ECR from Local env**

Require: AWS account and Dockerfile

Create project folder, and create file ``.aziona.yml`` with the snippet
below.

Create ECR repository in the AWS region where your profile is pointing.

Edit ``.aziona.yml`` and export to shell env vars:

1. export AWS_ACCESS_KEY_ID=xxx
2. export AWS_SECRET_ACCESS_KEY=xxx
3. export AWS_ACCOUNT_ID=xxx
4. export AWS_ECR_REGION=xxx
5. export AWS_ECR_REPOSITORY=xxx

Create sample Dockerfile.

Finally, run:

::

   aziona release

This aziona configuration file firstly makes login on Ecr service,
nextly, build docker image, and endly push image to ecr repository

Snippet

::

   version: "1"

   targets:
     release:
       stages:
         login:
           module: aziona.packages.docker.login_aws_credentials
           args: 
             --region: ${AWS_ECR_REGION}
             --registry: ${AWS_ECR_REGISTRY}
         build: 
           module: aziona.packages.docker.build
           args: 
             --path: .
             --dockerfile: Dockerfile
             --tag: ${DOCKER_IMAGE}
         push: 
           module: aziona.packages.docker.push
           args: 
             --image: ${DOCKER_IMAGE}

   env:
     AWS_ACCESS_KEY_ID: ${AWS_ACCESS_KEY_ID}
     AWS_SECRET_ACCESS_KEY: ${AWS_SECRET_ACCESS_KEY}
     AWS_ACCOUNT_ID: ${AWS_ACCOUNT_ID}
     AWS_ECR_REGION: ${AWS_ECR_REGION}
     AWS_ECR_REPOSITORY: ${AWS_ECR_REPOSITORY}
     AWS_ECR_REGISTRY: ${AWS_ACCOUNT_ID}.dkr.ecr.${AWS_ECR_REGION}.amazonaws.com
     DOCKER_IMAGE: ${AWS_ECR_REGISTRY}/${AWS_ECR_REPOSITORY}:latest

In the case in the local environment you want to use the aws profiles
configured in .aws/credentials you have to use the following
configuration:

1. You need to add this args ``--profile: ${AWS_PROFILE}`` to *login*
   stage

2. Change the env to and export vars:

::

   env:
     AWS_PROFILE: ${AWS_PROFILE}
     AWS_ACCOUNT_ID: ${AWS_ACCOUNT_ID}
     AWS_ECR_REGION: ${AWS_ECR_REGION}
     AWS_ECR_REPOSITORY: ${AWS_ECR_REPOSITORY}
     AWS_ECR_REGISTRY: ${AWS_ACCOUNT_ID}.dkr.ecr.${AWS_ECR_REGION}.amazonaws.com
     DOCKER_IMAGE: ${AWS_ECR_REGISTRY}/${AWS_ECR_REPOSITORY}:latest

..

   [WARNING] It is not recommended to put sensitive data directly into
   the env.

**Ex. Release docker image into Aws ECR from GitHub Action**

Let’s start with the “Local env” example.

Now that we’ve texted the process in a local environment, we can create
a pipeline in GitHub (or your reference system) that executes our
actions.

First, we need to create a “.github” folder in the root of the project
with another folder called “workflows” inside.

Create the following secrets in Github:

1. AWS_ACCESS_KEY_ID
2. AWS_SECRET_ACCESS_KEY
3. AWS_ACCOUNT_ID
4. AWS_ECR_REGION
5. AWS_ECR_REPOSITORY

Then create a release.yml file in .github/workflows and paste the
following code:

::

   name: Release docker image to AWS ECR

   on:
     push:
       branches:
         - "main"

   env:
     AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
     AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
     AWS_ACCOUNT_ID: ${{ secrets.AWS_ACCOUNT_ID }}
     AWS_ECR_REGION: ${{ secrets.AWS_ECR_REGION }}
     AWS_ECR_REPOSITORY: ${{ secrets.AWS_ECR_REPOSITORY }}

   jobs:
     release:
       name: Push image on ECR
       runs-on: ubuntu-20.04

       steps:
         - name: Checkout
         uses: actions/checkout@v2

         - name: Checkout Action - Aziona CLI
         uses: actions/checkout@v2
         with:
             repository: azionaventures/aziona-cli
             ref:  main
             path: .github/actions/aziona

         - name: Aziona cli
         uses: ./.github/actions/aziona
         with:
             target: release

This pipeline will be started whenever a push is made to the main. The
GitHub action of aziona-cli is used to execute the “release” target,
which will execute all the actions defined in the .aziona.yml file. This
way we can test the pipeline locally and be independent of the
versioning system.

**Ex. Release docker image into Aws ECR from Bitbucket pipeline**

Let’s start with the “Local env” example.

Create il file bitbucket-pipelines.yml nella root del progetto e
inserite il seguente codice:

::

   image:
     name: 

   options:
     docker: true

   pipelines:
     branches:
       main:
         - step:
             name: Release docker image to AWS ECR
             deployment: env
             image:
               name: azionaventures/aziona-cli:0.1
             script:
               - aziona release

Create deployment named *env*. Enter the following keys in the
deployment:

1. AWS_ACCESS_KEY_ID
2. AWS_SECRET_ACCESS_KEY
3. AWS_ACCOUNT_ID
4. AWS_ECR_REGION
5. AWS_ECR_REPOSITORY

The pipeline will use the action-cli:0.1 image to execute the step.

Contributing
------------

::

   1. Open issue 
   2. Use module `aziona.core` for I/O, logging, settings etc
   3. Formatting and fix code with `make lint`
   4. Merge request


.. toctree::
   :maxdepth: 3
   :name: references
   :caption: References API
   :titlesonly:

   references/cli/index
   references/core/index

.. toctree::
   :maxdepth: 2
   :name: changelog
   :caption: Changelog
   :titlesonly:
   :glob:

   changelog/*

   
License
-------

`GNU General Public License
v3.0 <https://github.com/azionaventures/aziona-cli/blob/main/LICENSE>`__

.. |image0| image:: https://img.shields.io/badge/version-0.1-green.svg
.. |image1| image:: https://img.shields.io/badge/docker--compose-build-blue.svg
.. |image2| image:: https://img.shields.io/badge/docker-build-blue.svg

Indice
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`