From 1d289a44fced6bc702cb66136aa0f62e343a7e00 Mon Sep 17 00:00:00 2001 From: Michele Sessa Date: Wed, 22 Mar 2023 17:40:15 +0000 Subject: [PATCH] docs(crud-master): improve subject and audit add references to microservices small typo fixes more generic version of environment variables section remove section about api-gateway being the only possible access require students to make a detailed readme file --- subjects/devops/crud-master/README.md | 51 ++++++--------------- subjects/devops/crud-master/audit/README.md | 4 +- 2 files changed, 16 insertions(+), 39 deletions(-) diff --git a/subjects/devops/crud-master/README.md b/subjects/devops/crud-master/README.md index 84090f164..f51cdf96e 100644 --- a/subjects/devops/crud-master/README.md +++ b/subjects/devops/crud-master/README.md @@ -3,13 +3,15 @@ ### Instructions APIs are a very common and convenient way to deploy services in a modular way. -In this exercise we will create a simple API infrastructure, having an API Gateway connected with two other APIs. -Those two APIs will in turn get data from two distinct databases. -The communication between APIs will be done by using HTTP and message queuing systems. +In this exercise we will create a simple microservices infrastructure, having an API Gateway connected to two other services. +Those two services will in turn get data from two distinct databases. +The communication between services will be done by using HTTP and message queuing systems. All those services will be in turn encapsulated in different virtual machines. #### General overview +![CRUD Master architecture diagram](resources/crud-master-diagram.png) + We will setup a movie streaming platform, where one API (`inventory`) will have information on the movies available and another one (`billing`) will process the payments. The API gateway will communicate in HTTP with `inventory` and using RabbitMQ for `billing`. @@ -55,7 +57,7 @@ The API should work on `http://localhost:8080/`. For the database we will use PostgreSQL. The database will be called `movies`. -Each movie will have the following columns: +The `movies` table will contain the following columns: - `id`: autogenerated unique identifier. - `title`: the title of the movie. @@ -92,7 +94,7 @@ When the API is started it will take and process all messages present in the que For the database we will use PostgreSQL here as well. The database will be called `orders`. -Each order will have the following columns: +The `orders` table will contain the following columns: - `id`: autogenerated unique identifier. - `user_id`: the id of the user making the order. @@ -110,7 +112,7 @@ To test this API here are some steps: #### The API Gateway -The Gateway will be the only service accessible by the user, it will take care of routing the requests to the appropriate API using the right protocol (it could be HTTP for API1 or RabbitMQ for API2). +The Gateway will take care of routing the requests to the appropriate service using the right protocol (it could be HTTP for the Inventory API or RabbitMQ for for the Billing API). ##### Interfacing with Inventory API @@ -144,11 +146,13 @@ Good documentation is a very critical feature of every API. By design the APIs a As an introduction to the art of great documentation you must create an OpenAPI documentation file for the API Gateway. There is many different ways to do so, a good start could be using SwaggerHub with at least a meaningful description for each endpoint. Feel free to implement any extra feature as you see fit. +> You must also create a `README.md` file at the root of your project with detailed instructions on how to build and run your infrastructure and which design choices you made to structure it. + #### Virtual Machines ##### General overview -You will use DropBox and Vagrant to setup three different VMs in order to test the interactions and correctness of responses between your APIs infrastructure. +You will use VirtualBox and Vagrant to setup three different VMs in order to test the interactions and correctness of responses between your APIs infrastructure. Vagrant is an open-source software that helps you create and manage virtual machines. With Vagrant, you can create a development environment that is identical to your production environment, which makes it easier to develop, test, and deploy your applications. @@ -164,38 +168,9 @@ Your VMs will be structured as follow: To simplify the building process it is a common practice to store useful variables in a `.env` file. It will make very easy to modify/update information like URLs, passwords, users and so on. -Those variables will then be used by Vagrant and passed through the different APIs in order to centralize all the credentials. - -Your `.env` file should contain the following variables: +Those variables will then be used by Vagrant and passed through the different microservices in order to centralize all the credentials. -```console -# postgres password -POSTGRES_PASSWORD=... -# postgres user for billing database -BILLING_DB_USER=... -# postgres password for billing database -BILLING_DB_PASSWORD=... -# postgres name for billing database -BILLING_DB_NAME=... -# postgres user for inventory database -INVENTORY_DB_USER=... -# postgres password for inventory database -INVENTORY_DB_PASSWORD=... -# postgres name for inventory database -INVENTORY_DB_NAME=... -# rabbitmq user -RABBITMQ_USER=... -# rabbitmq passowrd -RABBITMQ_PASSWORD=... -# rabbitmq port -RABBITMQ_PORT=5672 -# rabbitmq billing queue name -RABBITMQ_BILLING_QUEUE=billing_queue -# inventory api port -INV_APP_PORT=3001 -# apigateway api port -APIGATEWAY_PORT=3000 -``` +Your `.env` file should contain all the necessary credentials and none of the microservices should have any credential hardcoded in the source code. > For the purpose of this exercise the `.env` file must be included in your repository, though usually in public and production projects the `.env` file is never included in repos to avoid sensitive data leaks. diff --git a/subjects/devops/crud-master/audit/README.md b/subjects/devops/crud-master/audit/README.md index 6e2f0f691..babb4fa17 100644 --- a/subjects/devops/crud-master/audit/README.md +++ b/subjects/devops/crud-master/audit/README.md @@ -10,7 +10,9 @@ ##### Locate the `.env` file in the root of the project, run `cat .env`: -###### Does the output contains the variables listed in the `.env` example given in the subject? +###### Does the output contains all the necessary credentials for the microservices to run properly? + +###### Is the source code free from any credential that could have been added to the `.env` file? ###### Is the student able to explain the commands included in `/scripts` directory and why they are used?