Este proyecto contiene un ejemplo de solución SAM + Jenkins. Contiene una aplicación API RESTful de libreta de tareas pendientes (ToDo) y los pipelines que permiten definir el CI/CD para productivizarla.
A continuación se describe la estructura del proyecto:
- pipelines - pipelines de Jenkins que permiten construir el CI/CD
- src - en este directorio se almacena el código fuente de las funciones lambda con las que se va a trabajar
- test - Tests unitarios y de integración.
- samconfig.toml - Configuración de los stacks de Staging y Producción
- template.yaml - Template que define los recursos AWS de la aplicación
- localEnvironment.json - Permite el despliegue en local de la aplicación sobreescribiendo el endpoint de dynamodb para que apunte contra el docker de dynamo
Para utilizar SAM CLI se necesitan las siguientes herramientas:
- SAM CLI - Install the SAM CLI
- Python 3 installed - Se ha testeado con Python 3.7
- Docker - Install Docker community edition
sam build
Ejecutar el siguiente comando para el entorno de staging
sam deploy template.yaml --config-env staging
Ejecutar el siguiente comando para el entorno de producción
sam deploy template.yaml --config-env prod
Sin utilizar la configuración del archivo samconfig.toml. Se generará un archivo de configuración reemplazando al actual si ya existe. Ejecutar el siguiente comando:
sam deploy --guided
El despliegue de la aplicación empaqueta, publicará en un bucket s3 el artefacto y desplegará la aplicación en AWS. Solicitará la siguiente información
- Stack Name: El nombre del stack que desplegará en CloudFormation. Debe ser único
- AWS Region: La región en la que se desea publicar la Aplicación.
- Confirm changes before deploy: Si se indica "yes" se solicitará confirmación antes del despliegue si se encuentran cambios
- Allow SAM CLI IAM role creation: Permite la creación de roles IAM
- Save arguments to samconfig.toml: Si se selecciona "yes" las respuestas se almacenarán en el fichero de configuración samconfig.toml, de esta forma el el futuro se podrá ejecutar con
sam deploy
y se leerá la configuración del fichero.
En el output del despliegue se devolverá el API Gateway Endpoint URL
A continuación se describen los comandos/acciones a realizar para poder probar la aplicación en local:
## Crear red de docker
docker network create sam
## Levantar el contenedor de dynamodb en la red de sam con el nombre de dynamodb
docker run -p 8000:8000 --network sam --name dynamodb -d amazon/dynamodb-local
## Crear la tabla en local, para poder trabajar localmemte
aws dynamodb create-table --table-name local-TodosDynamoDbTable --attribute-definitions AttributeName=id,AttributeType=S --key-schema AttributeName=id,KeyType=HASH --provisioned-throughput ReadCapacityUnits=1,WriteCapacityUnits=1 --endpoint-url http://localhost:8000
## Empaquetar sam
sam build # también se puede usar sam build --use-container si se dan problemas con las librerías de python
## Levantar la api en local, en el puerto 8080, dentro de la red de docker sam
sam local start-api --port 8080 --env-vars localEnvironment.json --docker-network sam
Se pueden consultar en CloudWath o ejecutando un comando similar al siguiente:
sam logs -n GetTodoFunction --stack-name todo-list-aws-staging
Se encuentran en la carpeta test
que tiene la siguiente estructura:
- test
|--- integration (tests de integración)
| -- todoApiTest.py
|--- unit (tests unitarios)
| -- TestToDo.py
Para ejecutar los tests de integración es necesario ejecutar los siguientes comandos:
python -m pip install pytest
python -m pip install requests
pytest -s test/integration/todoApiTest.py
Para ejecutar los tests unitarios es necesario ejecutar los siguientes comandos:
python3.7 -m venv pyenvunittests
source pyenvunittests/bin/activate
python3.7 -m pip install --upgrade pip
python3.7 -m pip install boto3
python3.7 -m pip install moto
python3.7 -m pip install mock==4.0.2
python3.7 -m pip install coverage==4.5.4
export PYTHONPATH="${PYTHONPATH}:<directorio de la aplicación>"
export DYNAMODB_TABLE=todoUnitTestsTable
python test/unit/TestToDo.py
Para la implementación del CI/CD de la aplicación se utilizan los siguientes Pipelines:
- PIPELINE-FULL-STAGING: (PIPELINE-FULL-STAGING/Jenkinsfile) Este pipeline es el encargado de configurar el entorno de staging y ejecutar las pruebas
- PIPELINE-FULL-PRODUCTION: (PIPELINE-FULL-PRODUCTION/Jenkinsfile) Este pipeline es el encargado de configurar el entorno de production y ejecutar las pruebas
- PIPELINE-FULL-CD: este pipeline es el encargado de enganchar los pipelines de staging y production, con el objetivo de completar un ciclo de despliegue continuo desde un commit al repositorio de manera automática.
Para borrar la apliación y eliminar los stacks creados ejecutar los siguientes comandos:
aws cloudformation delete-stack --stack-name todo-list-aws-staging
aws cloudformation delete-stack --stack-name todo-list-aws-production