Add support for environment variable configuration. (#25)

* Add support for environment variable configuration.
* Add docs.
* Set environment variables before activation, only if they are an array
* Docs

Co-authored-by: Adrian Brown <adrian.brown@plantracker.com.au>
Co-authored-by: Aaron Francis <aarondfrancis@gmail.com>

Author: 3 people

docs/functions/customization.md

@@ -5,7 +5,7 @@ The only two things _required_ for a Sidecar function are the [package and the h
 
 ## Runtime
 
-Lambda supports multiple languages through the use of runtimes. You can choose any of the following runtimes by returning its corresponding identifier: 
+Lambda supports multiple languages through the use of runtimes. You can choose any of the following runtimes by returning its corresponding identifier:
 
 - Node.js 14: `nodejs14.x`
 - Node.js 12: `nodejs12.x`
@@ -20,16 +20,16 @@ Lambda supports multiple languages through the use of runtimes. You can choose a
 - Java 8: `java8`
 - Go 1.x: `go1.x`
 - .NET Core 3.1: `dotnetcore3.1`
-- .NET Core 2.1: `dotnetcore2.1` 
+- .NET Core 2.1: `dotnetcore2.1`
 
 E.g. to use the Go runtime, you would return `go1.x`:
 
 ```php
 class ExampleFunction extends LambdaFunction
 {
-    public function runtime() // [tl! focus:3] 
+    public function runtime() // [tl! focus:3]
     {
-        return 'go1.x'; 
+        return 'go1.x';
     }
 }
 ```
@@ -49,7 +49,7 @@ To change the allocated memory of your function, return the number in megabytes.
 ```php
 class ExampleFunction extends LambdaFunction
 {
-    public function memory() //  [tl! focus:4] 
+    public function memory() //  [tl! focus:4]
     {
         // 2GB of memory
         return 2048;
@@ -80,7 +80,7 @@ class ExampleFunction extends LambdaFunction
 
 ## Layers
 
-Some functions require extra code or data beyond what is in your code package. From [Amazon's documentation](https://docs.aws.amazon.com/lambda/latest/dg/configuration-layers.html): 
+Some functions require extra code or data beyond what is in your code package. From [Amazon's documentation](https://docs.aws.amazon.com/lambda/latest/dg/configuration-layers.html):
 
 > A Lambda layer is a .zip file archive that can contain additional code or data. A layer can contain libraries, a custom runtime, data, or configuration files. Layers promote code sharing and separation of responsibilities so that you can iterate faster on writing business logic.
 
@@ -92,43 +92,102 @@ class ExampleFunction extends LambdaFunction
 {
     public function handler()
     {
-        // 
+        //
     }
 
     public function package()
     {
         //
     }
-    
-    public function layers() // [tl! focus:start] 
+
+    public function layers() // [tl! focus:start]
     {
         return [
-            // Node Canvas from https://github.com/jwerre/node-canvas-lambda 
-            'arn:aws:lambda:us-east-2:XXXX:layer:node_canvas:1', 
-        ];       
+            // Node Canvas from https://github.com/jwerre/node-canvas-lambda
+            'arn:aws:lambda:us-east-2:XXXX:layer:node_canvas:1',
+        ];
     } // [tl! focus:end]
 }
 ```
 
 Note that your layers must be in the same AWS region as your Lambdas!
 
+## Environment Variables
+
+Some functions or layers may require configuration via Lambda environment variables. The Lambda runtime makes environment variables available to the code.
+
+In this example below, we're providing a path to a font directory as an environment variable.
+```php
+class ExampleFunction extends LambdaFunction
+{
+    public function handler()
+    {
+        //
+    }
+
+    public function package()
+    {
+        //
+    }
+
+    public function variables() // [tl! focus:start]
+    {
+        return [
+            'FONTCONFIG_PATH' => '/opt/etc/fonts',
+        ];
+    } // [tl! focus:end]
+}
+```
+
+It is **very important** to note that if you allow Sidecar to manage your Lambda's environment variables, any changes made to environment variables in the AWS UI will be overwritten next time you deploy your function. 
+
+By default, Sidecar doesn't touch your Lambda's environment at all. Only when you return an array from `variables` will Sidecar take control of the env vars.
+
+Another important thing to note is that Sidecar sets your environment variables as a part of the _activation_ process, not the _deploy_ process. This means that the environment variables will be pulled from the machine that calls `sidecar:activate`.
+
+For example, if you are sharing secrets with your Lambda, then the values passed to your Lambda will be equal to the ones on the machine that called `sidecar:activate`, not the one that called `sidecar:deploy`:
+
+```php
+class ExampleFunction extends LambdaFunction
+{
+    public function handler()
+    {
+        //
+    }
+
+    public function package()
+    {
+        //
+    }
+
+    public function variables()  // [tl! focus:start]
+    {
+        // Values will come from the "activating" machine. 
+        return [
+            'aws_key' => config('services.aws.key'),
+            'aws_secret' => config('services.aws.secret'),
+        ];
+    } // [tl! focus:end]
+}
+```
+
 ## Name
 
 Your function has a `name` method that determines how Sidecar names your Lambda functions. By default it is based on the name and path of your PHP class. You are free to change this if you want, but you're unlikely to need to.
 
 ```php
 class ExampleFunction extends LambdaFunction
 {
-    public function name() // [tl! focus:3] 
+    public function name() // [tl! focus:3]
     {
-        return 'Function Name'; 
+        return 'Function Name';
     }
 }
 ```
 
 ### Name Prefix
 
-Regardless of what you choose for your function names, Sidecar will prepend the name of your app and the current environment. 
+Regardless of what you choose for your function names, Sidecar will prepend the name of your app and the current environment.
 
 Lambda function names must be unique, so adding these variables to your function names prevents collisions between different apps and environments.
 
@@ -143,7 +202,7 @@ You likely won't need to change this, but if you do, *you must include the envir
             // Don't forget the environment!
             return 'My App ' . Sidecar::getEnvironment()
         }
-    }       
+    }
 ```
 
 ## Description

src/Deployment.php

@@ -123,6 +123,8 @@ protected function activateSingle(LambdaFunction $function, $prewarm)
     {
         $function->beforeActivation();
 
+        $this->setEnvironmentVariables($function);
+
         if ($prewarm) {
             $this->warmLatestVersion($function);
         }
@@ -158,6 +160,29 @@ protected function updateExistingFunction(LambdaFunction $function)
         }
     }
 
+    /**
+     * Add environment variables to the Lambda function, if they are provided.
+     *
+     * @param LambdaFunction $function
+     */
+    protected function setEnvironmentVariables(LambdaFunction $function)
+    {
+        $variables = $function->variables();
+
+        if (!is_array($variables)) {
+            return Sidecar::log('Environment variables not managed by Sidecar. Skipping.');
+        }
+
+        Sidecar::log('Updating environment variables.');
+
+        $this->lambda->updateFunctionConfiguration([
+            'FunctionName' => $function->nameWithPrefix(),
+            'Environment' => [
+                'Variables' => $variables,
+            ],
+        ]);
+    }
+
     /**
      * Send warming requests to the latest version.
      *

src/LambdaFunction.php

@@ -209,6 +209,20 @@ public function layers()
         ];
     }
 
+    /**
+     * A key/value array of environment variables that will be injected into the
+     * environment of the Lambda function. If Sidecar manages your environment
+     * variables, it will overwrite all variables that you set through the
+     * AWS UI. Return false to disable.
+     *
+     * @return bool|array
+     */
+    public function variables()
+    {
+        // By default, Sidecar does not manage your environment variables.
+        return false;
+    }
+
     /**
      * The function within your code that Lambda calls to begin execution.
      * For Node.js, it is the `module-name.export` value in your function.

tests/Unit/DeploymentTest.php

@@ -14,6 +14,7 @@
 use Hammerstone\Sidecar\Events\BeforeFunctionsDeployed;
 use Hammerstone\Sidecar\Exceptions\NoFunctionsRegisteredException;
 use Hammerstone\Sidecar\Tests\Unit\Support\DeploymentTestFunction;
+use Hammerstone\Sidecar\Tests\Unit\Support\DeploymentTestFunctionWithVariables;
 use Illuminate\Support\Facades\Event;
 use Mockery;
 
@@ -197,6 +198,31 @@ public function it_updates_and_activates_an_existing_function()
         $this->assertEvents($deployed = true, $activated = true);
     }
 
+    /** @test */
+    public function it_sets_environment_variables()
+    {
+        $this->lambda->shouldReceive('functionExists')->andReturn(true);
+        $this->lambda->shouldReceive('getVersions')->andReturn([]);
+        $this->lambda->shouldReceive('updateExistingFunction')->once()->withArgs(function ($function) {
+            return $function instanceof DeploymentTestFunctionWithVariables;
+        });
+
+        $this->lambda->shouldReceive('updateFunctionConfiguration')->with([
+            'FunctionName' => 'test-FunctionName',
+            'Environment' => [
+                'Variables' => [
+                    'env' => 'value'
+                ],
+            ],
+        ]);
+
+        $this->mockActivating();
+
+        DeploymentTestFunctionWithVariables::deploy($activate = true);
+
+        $this->assertEvents($deployed = true, $activated = true);
+    }
+
     /** @test */
     public function it_throws_an_exception_if_there_are_no_functions()
     {

tests/Unit/Support/DeploymentTestFunctionWithVariables.php

@@ -0,0 +1,20 @@
+<?php
+/**
+ * @author Aaron Francis <aarondfrancis@gmail.com|https://twitter.com/aarondfrancis>
+ */
+
+namespace Hammerstone\Sidecar\Tests\Unit\Support;
+
+use Hammerstone\Sidecar\LambdaFunction;
+use Hammerstone\Sidecar\WarmingConfig;
+
+class DeploymentTestFunctionWithVariables extends DeploymentTestFunction
+{
+    public function variables()
+    {
+        return [
+            'env' => 'value'
+        ];
+    }
+
+}