Le Blog Amazon Web Services

Utiliser GitHub Actions pour deployer des applications “Serverless”

L’intégration continue et le déploiement continu (CI/CD – Continuous Integration/Continuous Delivery) fait partie intégrante de la démarche DevOps. Elle vous permet de construire, tester et déployer vos applications rapidement et de manière fiable, ainsi que d’améliorer la qualité du code et réduire le temps de mise sur le marché (time to market).

Dans cet article, vous apprendrez comment créer une application Serverless d’exemple en utilisant AWS SAM. Vous utiliserez ensuite GitHub Actions pour construire et déployer cette application dans votre compte AWS.

GitHub est membre du réseau AWS Partner Network (APN) avec la compétence AWS DevOps. GitHub Actions (présentation en anglais) est une fonctionnalité GitHub qui permet d’automatiser des tâches au sein de votre cycle de développement d’applications. Vous pouvez utiliser GitHub Actions pour exécuter un pipeline de CI/CD servant à construire, tester et déployer des applications directement depuis GitHub.
AWS Serverless Application Model (AWS SAM) est un framework open-source pour construire des applications Serverless. Il fournit des raccourcis pour définir des fonctions, des APIs, des bases de données et des mappages de source d’évènements (« event source mapping »). Avec seulement quelques lignes par ressource, vous pouvez créer une application et la modéliser en utilisant des fichiers au format YAML.

Pendant le déploiement, AWS SAM transforme et étend la syntaxe vers AWS CloudFormation, vous fournissant un moyen de construire des applications Serverless plus rapidement. AWS SAM CLI vous permet de construire, tester et debugger vos applications sur votre environnement local, en partant de la définition des modèles (templates) AWS SAM. Vous pouvez consulter cet ensemble de patterns Serverless pour voir des exemples de code.

Nouvelle action GitHub setup-sam

Un runner GitHub Actions est une application qui exécute une tâche depuis un processus de configuration automatisé (workflow) GitHub Actions. Vous pouvez utiliser un GitHub hosted runner (article en anglais), qui est une machine virtuelle lancée par GitHub avec l’application runner pré-installée. Vous pouvez également choisir de lancer votre propre runner afin de personnaliser l’environnement utilisé par les tâches dans vos workflows GitHub Actions.

AWS a publié une action GitHub appelée setup-sam pour installer AWS SAM, qui est pré-installé sur les hosted runners GitHub (article en anglais) Vous pouvez utiliser cette action pour choisir une version spécifique ou bien la dernière version d’AWS SAM.

Cette démonstration utilise AWS SAM pour créer une application Serverless d’exemple en utilisant un des templates intégré. Lorsque le code est envoyé sur GitHub, un workflow GitHub Actions déclenche un pipeline de CI/CD GitHub : il construira et déploiera votre code directement depuis GitHub vers votre compte AWS.

Pré-requis

  • Un compte GitHub : Cet article part du principe que vous avez les permissions nécessaires à la configuration des dépôts GitHub et la création de workflows.
  • Créez un nouveau dépôt GitHub et récupérez-le (clone) sur votre environnement de travail local. Pour cet exemple, créez un dépôt github-actions-with-aws-sam.
  • Un compte AWS avec les permissions pour créer les ressources nécessaires.
  • Installez AWS Command Line Interface (CLI) et AWS SAM CLI sur votre environnement de travail local. Cela est différent de l’installation d’AWS SAM CLI dans un runner GitHub Actions. Si vous utilisez AWS Cloud9 en tant qu’IDE (integrated development environment), AWS CLI et AWS SAM sont déjà pré-installés.
  • Créez un bucket Amazon S3 dans votre compte AWS pour pouvoir stocker le package construit servant au déploiement.
  • Un rôle AWS Identity and Access Management (IAM) qui sera utilisé par le runner GitHub Actions pour déployer l’application. Ce rôle aura également d’accéder en lecture et écriture au bucket S3 créé précédemment.

Création de l’application AWS SAM

Vous pouvez créer une application Serverless en déclarant toutes les ressources requises dans un fichier template au format AWS SAM. AWS SAM fournit plusieurs templates “quick-start“ pour créer une application et démarrer rapidement.

  • Depuis la ligne de commande (CLI), ouvrez un terminal et déplacez vous dans le dossier parent du dépôt cloné et entrez la commande suivante :
sam init -r python3.8 -n github-actions-with-aws-sam --app-template "hello-world"
  • Choisissez zip pour “package type (zip or image)“ lorsque vous y serez invité

Ceci crée une application AWS SAM à la racine du dépôt github-actions-with-aws-sam, en utilisant la configuration par défaut. Cela revient à créer une function AWS Lambda Python 3.8 exécutée depuis un point d’entrée (endpoint) Amazon API Gateway.

Pour voir tous les environnements d’exécutions supportés par AWS SAM ainsi que les options pour sam init, utilisez la commande sam init -h.

Test local

AWS SAM vous permet de tester vos applications sur votre environnement de travail local. AWS SAM fournit un évènement par défaut dans events/event.json qui inclus le contenu de message {\"message\": \"hello world\"}.

  • Exécutez la fonction Lambda HelloWorldFunction sur votre environnement local, en utilisant l’évènement par défaut :
sam local invoke HelloWorldFunction -e events/event.json
  • La réponse de la function est :
{"message": "hello world"}
  • Testez la fonctionnalité de l’API Gateway devant la fonction Lambda en démarrant l’API sur votre environnement local :
sam local start-api
  • AWS SAM lance un conteneur Docker avec une API Gateway émulée dont le point d’entrée écoute sur localhost:3000.
  • Utilisez curl pour joindre l’API hello :
curl http://127.0.0.1:3000/hello

La réponse de l’API devrait être :
{"message": "hello world"}

Création du fichier sam-pipeline.yml

Les pipelines GitHub CI/CD sont configurés au travers d’un fichier YAML. Ce fichier (documentation en anglais) définit quelles actions déclenchent le workflow, comme par exemple un push sur la branche main du dépôt, et quelles étapes du workflow seront lancées.

Dans le répertoire racine contenant les fichiers générés par la commande précédente  sam init, créez le dossier : .github/workflows.

    1. Créez un nouveau fichier sam-pipeline.yml dans le dossier .github/workflows.

Fichier sam-pipeline.yml

    1. Editez le fichier sam-pipeline.yml et ajoutez :
on:
  push:
    branches:
      - main
permissions:
  id-token: write
  contents: write
env:
  BUCKET_NAME : "##s3-bucket##"
  AWS_REGION : "##region##"
  ASSUME_ROLE : "##iam_role##"
jobs:
  build-deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-python@v2
      - uses: aws-actions/setup-sam@v1
      - uses: aws-actions/configure-aws-credentials@master
        with:
          aws-region: ${{ env.AWS_REGION }}
          role-to-assume: ${{ env.ASSUME_ROLE }}
      # sam build 
      - run: sam build --use-container
# Run Unit tests- Specify unit tests here 
# sam deploy
      - run: sam deploy --no-confirm-changeset --no-fail-on-empty-changeset --stack-name sam-hello-world --s3-bucket ${{ env.BUCKET_NAME }} --capabilities CAPABILITY_IAM --region ${{ env.AWS_REGION }}
  1. Remplacez ##s3-bucket## par le nom du bucket S3 précédemment créé pour stocker le package de déploiement.
  2. Remplacez ##region## par la région AWS dans laquelle vous avez créé le bucket S3 et dans laquelle vous souhaitez que AWS SAM créé les ressources.

Cette configuration déclenche un pipeline de CI/CD GitHub Actions lorsque du code est envoyé dans la branche main. Vous pouvez la modifier si vous utilisez une autre branche. La liste de tous les types d’évènements supportés sont référencés sur la page de documentation GitHub (documentation en anglais).

Vous pouvez changer la façon dont la commande sam build --use-container s’exécute. Par défaut, l’image Docker utilisée pour créer le package de déploiement est récupérée depuis le registre (registry) Amazon ECR (documentation en anglais). L’image Python 3.8 utilisée par défaut dans cet exemple vient du language spécifié lors de l’exécution de la commande sam init. Pour utiliser une image de conteneur différente, utilisez l’option --build-image comme spécifié dans la documentation.

Le CLI AWS et le CLI AWS SAM sont installés dans le runner utilisé par l’action GitHub setup-sam. Pour installer une version particulière, utilisez le paramètre version.

uses: aws-actions/setup-sam@v1
with:
  version: 1.23.0

Dans la définition de pipelines CI/CD, nous vous recommandons de scanner votre code pour vérifier la qualité et les vulnérabilités dans les bibliothèques que vous récupérez. Vous pouvez trouver des propositions orientées sécurité sur la page des partenaires technologiques AWS Lambda. Le service Amazon CodeGuru peut également vous aider à détecter des failles de sécurité et faire des recommandations dans vos pipelines GitHub Actions (documentation en anglais).

Autoriser les runners GitHub à se connecter sur AWS

Le pipeline de CI/CD GitHub Actions nécessite d’avoir accès à la plateforme AWS pour agir sur les ressources. Depuis Octobre 2021, l’action GitHub configure-aws-credentials est compatible avec OpenID Connect (couche d’identification au dessus de OAuth 2.0). AWS IAM supporte également cette couche d’identification en tant que fournisseur d’identité (IdP : Identity Provider). Il n’est donc pas nécessaire de créer un utilisateur avec des clés d’API dans AWS IAM et de gérer la rotation de celles-ci. Il suffit de créer un rôle AWS IAM qui sera assumé par le runner GitHub Actions lors de son exécution. L’utilisation de ce rôle générera des clés temporaires qui seront utilisées et changées automatiquement. Ce rôle doit inclure des stratégies (policy) de sécurité AWS Identity and Access Management (IAM) qui autorisent l’accès aux services Lambda, API Gateway, AWS CloudFormation, S3 et IAM, requises pour permettre à AWS SAM de déployer les ressources correspondantes.

Plusieurs étapes sont nécessaires :

  • Ajoutez le fournisseur d’identité (IdP) GitHub dans la console AWS IAM. Cette action n’est à réaliser qu’une seule fois, quelque soit le nombre de rôles que vous créerez par la suite. Ce fournisseur n’a besoin d’être créé qu’une seule fois dans le compte AWS et peut-être partagé pour plusieurs rôles IAM.
  • Créez un rôle IAM
    • Attachez ou ajoutez les stratégies de sécurité nécessaires à AWS SAM. Vous pouvez retrouver la liste des permissions détaillées dans la documentation d’AWS SAM.
    • Utilisez le fournisseur d’identité précédemment créé pour établir une relation d’approbation (trust relationship : entité de confiance) ainsi qu’une condition pour que le rôle ne puisse être assumé que depuis le dépôt GitHub que vous avez choisi. Voici un exemple de condition autorisant toutes les branches d’un dépôt à assumer ce rôle (remplacez ##organization## et ##repository## par les valeurs adéquates) :
Condition Clé Valeur
StringLike token.actions.githubusercontent.com:sub repo:##organization##/##repository##:*
  • Récupérez l’ARN (Amazon Resource Name, au format arn:aws:iam::<account>:role/<role-name>) du rôle IAM et remplacez ##iam_role## par cet ARN dans le fichier GitHub Actions sam-pipeline.yml au niveau de la déclaration de la tâche configure-aws-credentials.

Consultez Configuring OpenID Connect in Amazon Web Services dans la documentation de GitHub pour plus de détails.

De manière générale sur IAM, nous recommandons d’appliquer les bonnes pratiques IAM suivantes :

    • Créez un rôle différent pour chaque workflow GitHub Actions, de préférence un par dépôt.
    • Accordez le moins de privilèges possibles au rôle utilisé par les workflows GitHub Actions. N’autorisez que les permissions nécessaires pour effectuer les actions depuis les workflows GitHub Actions.
    • Surveillez l’activité du rôle utilisé par les workflow GitHub Actions.

Déployer votre application

Ajouter tous les fichiers de votre dépôt local git (add), faites un commit des changements, et envoyez les (push) sur GitHub.

git add .
git commit -am "Add AWS SAM files"
git push

Une fois les fichiers envoyés sur GitHub sur la branche main, le pipeline GitHub Actions CI/CD sera déclenché automatiquement, tel que spécifié par le fichier sam-pipeline.yml.

Le runner GitHub actions exécute chaque étape du pipeline indiqué dans ce fichier. Il commence par récupérer le code depuis votre dépôt, configure Python, et s’identifie auprès d’AWS en assumant le rôle IAM. Le runner utilise l’action GitHub setup-sam pour installer le CLI AWS SAM.

Le pipeline déclenche le processus sam build pour construire le package de déploiement de l’application, en utilisant l’image de conteneur par défaut pour Python 3.8.
sam deploy s’exécute ensuite pour configurer les ressources dans votre compte AWS en utilisant le rôle IAM et les permissions associées.

Pour vérifier le déroulement du déploiement de l’application, choisissez Actions dans le menu du dépôt GitHub. Sélectionnez l’exécution (run) du workflow et sélectionnez la tâche (job) nommée build-deploy.

Déroulement du workflow GitHub Actions

Si la construction échoue, vous devrez lire les différents messages. Les erreurs les plus fréquentes sont :

    • Des incompatibilités entre versions de composants comme l’environnement d’exécution Python si il est différent entre celui d’AWS SAM et celui de la machine de construction. Pour résoudre ceci, vous devrez faire correspondre les versions.
    • L’action configure-aws-credentials échoue : le rôle IAM ne peut être assumé. Vérifiez les entités de confiance et la condition au niveau du rôle IAM dans la console AWS IAM.
    • Assurez-vous que le rôle AWS a les permissions nécessaires pour déployer les ressources indiquées dans le template AWS SAM, et également les droits sur le bucket S3 de déploiement.

Test de l’application

  • Dans l’exécution du job du workflow GitHub build-deploy, dépliez l’étape commençant par Run sam deploy.
  • Allez jusqu’à la section Outputs d’AWS SAM. La valeur (Value) de HelloWorldApi contiendra l’URL du point d’entrée de l’API Gateway déployée dans votre compte AWS.
CloudFormation outputs from deployed stack
-------------------------------------------------------------------------------------------------
Outputs
-------------------------------------------------------------------------------------------------
Key                 HelloWorldFunctionIamRole                                                  
Description         Implicit IAM Role created for Hello World function                          
Value               arn:aws:iam::***:role/sam-hello-world-HelloWorldFunctionRole-XXXXXX
Key                 HelloWorldApi
Description         API Gateway endpoint URL for Prod stage for Hello World function
Value               
https://xxxxxx.execute-api.eu-west-3.amazonaws.com/Prod/hello/
  • Utilisez curl pour tester l’API :
curl https://<api-id>.execute-api.eu-west-3.amazonaws.com/Prod/hello/

La réponse de l’API devrait être :{"message": "hello world"}

Suppression des ressources

Pour supprimer les ressources de l’application qui ont été créées, rendez-vous sur la console CloudFormation et supprimez la pile (stack) sam-hello-world. Vous pouvez également utiliser le CLI AWS CLI pour supprimer cette stack :

aws cloudformation delete-stack --stack-name sam-hello-world

Videz, et supprimez enfin le bucket S3 de déploiement.

Conclusion

GitHub Actions est une fonctionnalité GitHub qui vous permet d’exécuter un pipeline de CI/CD pour construire, tester, et déployer des applications directement depuis GitHub. AWS SAM est un framework open-source pour construire des applications Serverless.

Dans cet article, nous avons illustré comment vous pouvez vous appuyer sur les pipelines CI/CD de GitHub Actions et AWS SAM pour créer, construire, tester, et déployer une application Serverless. La commande sam init a également été utilisée pour créer une application Serverless et tester son fonctionnement sur votre environnement local. Enfin, le fichier sam-pipeline.ymla été créé pour définir les étapes du pipeline GitHub Actions.

L’action GitHub setup-sam a installé AWS SAM sur le runner GitHub. Le workflow GitHub Actions a utilisé sam build pour créer le package de déploiement de l’application et sam deploy pour les déployer dans votre compte AWS.

Pour en apprendre plus sur l’univers Serverless, vous pouvez consulter https://serverlessland.com.

Article original initialement publié par Gopi Krishnamurthy, Senior Solutions Architect et adapté en français par Guillaume Delacour, Solutions Architect dans l’équipe AWS France.