From 1c438a22891eb2d2e19e12e71c80e75ebaca463e Mon Sep 17 00:00:00 2001
From: ttacquet <ttacquet@scaleway.com>
Date: Tue, 31 May 2022 16:18:54 +0200
Subject: [PATCH] add documentation about credentials management

---
 README.md      | 42 +++++++++++++++++++++++++++++++++++++++++-
 docs/README.md | 34 ++++++++++++++++++++++++++++------
 2 files changed, 69 insertions(+), 7 deletions(-)

diff --git a/README.md b/README.md
index 5db50dca..ceec6ad0 100644
--- a/README.md
+++ b/README.md
@@ -8,6 +8,7 @@ Serverless Framework handles everything from creating namespaces to function/cod
   - [Requirements](#requirements)
   - [Create a Project](#create-a-project)
   - [Configure your functions](#configure-your-functions)
+    - [Security and secret management](#security-and-secret-management)
   - [Functions Handler](#functions-handler)
     - [Node](#node)
     - [Python](#python)
@@ -56,15 +57,18 @@ Your functions are defined in the `serverless.yml` file created:
 service: scaleway-python3
 configValidationMode: off
 
+useDotenv: true
+
 provider:
   name: scaleway
   runtime: python310
   # Global Environment variables - used in every functions
   env:
     test: test
+  # Storing credentials in this file is strongly not recommanded for security concerns, please refer to README.md about best practices
   scwToken: <scw-token>
   scwProject: <scw-project-id>
-  # region in which the deployment will happen, (default fr-par)
+  # region in which the deployment will happen (default: fr-par)
   scwRegion: <scw-region>
 
 plugins:
@@ -91,6 +95,8 @@ of the same runtime (here `python3`)
 
 The different parameters are:
 * `service`: your namespace name
+* `useDotenv`: Load environment variables from .env files (default: false), read [Security and secret management](#security-and-secret-management)
+* `configValidationMode`: Configuration validation: 'error' (fatal error), 'warn' (logged to the output) or 'off' (default: warn)
 * `provider.runtime`: the runtime of your functions (check the supported runtimes above)
 * `provider.env`: environment variables attached to your namespace are injected to all your namespace functions
 * `scwToken`: Scaleway token you got in prerequisites
@@ -107,6 +113,40 @@ The different parameters are:
   * `runtime`: (Optional) runtime of the function, if you need to deploy multiple functions with different runtimes in your Serverless Project. If absent, `provider.runtime` will be used to deploy the function, see [this example project](./examples/multiple).
   * `events` (Optional): List of events to trigger your functions (e.g, trigger a function based on a schedule with `CRONJobs`). See `events` section below
 
+### Security and secret management
+
+You configuration file may contains sensitive data, your project ID and your Token must not be shared and must not be commited in VCS.
+
+To keep your informations safe and be able to share or commit your `serverles.yml` file you should remove your credentials from the file. Then
+you can :
+- use global environment variables
+- use `.env` file and keep it secret
+
+To use `.env` file you can modify your `serverless.yml` file as following :
+
+```yml
+# This will alow the plugin to read your .env file
+useDotenv: true
+
+provider:
+  name: scaleway
+  runtime: node16
+
+  scwToken: ${env:SCW_SECRET_KEY}
+  scwProject: ${env:SCW_DEFAULT_PROJECT_ID}
+  scwRegion: ${env:SCW_REGION}
+```
+
+And then create a `.env` file next to your `serverless.yml` file, containing following values :
+
+```bash
+SCW_SECRET_KEY=XXX
+SCW_DEFAULT_PROJECT_ID=XXX
+SCW_REGION=fr-par
+```
+
+You can use this pattern to hide your secrets (for example a connexion string to a database or a S3 bucket).
+
 ## Functions Handler
 
 Based on the chosen runtime, the `handler` variable on function might vary.
diff --git a/docs/README.md b/docs/README.md
index c3c95165..3cdd0e08 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -60,19 +60,30 @@ Now, when running `serverless` commands from your project directory, serverless
 
 ### Use your credentials
 
-Once you retrieved your `project ID` and created a new `token`, you will have to use these credentiasl with the Serverless Framework.
+Once you retrieved your `project ID` and created a new `token`, you will have to use these credentials with the Serverless Framework.
 
 There are multiple ways to do it:
 
-- **serverless.yml** manifest. Inside your manifest, you may inquire your credentials with the following structure under the `provider` key:
+- **Using `.env` file** (recommanded):
+
 ```yml
+# This will alow the plugin to read your .env file
+useDotenv: true
+
 provider:
-  scwToken: <scw-token>
-  scwProject: <scw-project-id>
+  name: scaleway
+  runtime: node16
+
+  scwToken: ${env:SCW_SECRET_KEY}
+  scwProject: ${env:SCW_DEFAULT_PROJECT_ID}
 ```
-- **CLI arguments**:
 
-[link to CLI documentation](https://github.com/scaleway/scaleway-cli/blob/master/docs/commands/function.md)
+Create a `.env` file next to your `serverless.yml` file : 
+
+```bash
+SCW_SECRET_KEY=XXX
+SCW_DEFAULT_PROJECT_ID=XXX
+```
 
 - **Environment variables**:
 ```bash
@@ -81,6 +92,17 @@ export SCW_PROJECT=<scw-project-id>
 serverless deploy
 ```
 
+- **CLI arguments**:
+
+[link to CLI documentation](https://github.com/scaleway/scaleway-cli/blob/master/docs/commands/function.md)
+
+- **serverless.yml** (discouraged) manifest. Inside your manifest, you may inquire your credentials with the following structure under the `provider` key:
+```yml
+provider:
+  scwToken: <scw-token>
+  scwProject: <scw-project-id>
+```
+
 The priority order is the following (from top: + priority to bottom: - priority):
 - CLI
 - Environment variables