Skip to content

Commit

Permalink
Docs
Browse files Browse the repository at this point in the history
  • Loading branch information
aarondfrancis committed Jul 12, 2021
1 parent 7272746 commit d3ba88f
Show file tree
Hide file tree
Showing 17 changed files with 895 additions and 532 deletions.
7 changes: 4 additions & 3 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,20 +1,21 @@
# Changelog

## Unreleased

## 0.2.0 - 2021-07-12

### Added
- New `sidecar.env` config option to separate Sidecar environment from application environment. Useful mostly for teams who have multiple developers that all have an app env of `local` and don't want to be constantly overwriting each other's functions.
- New `sidecar:warm` command ([#6](https://github.com/hammerstonedev/sidecar/pull/6))
- Better error reporting when `sidecar:deploy` is called and there are no functions.
- Better error reporting when a function is not found.
- Implemented Sweeping to remove old, unused function versions ([#15](https://github.com/hammerstonedev/sidecar/pull/15))
- Implemented sweeping to remove old, unused function versions ([#15](https://github.com/hammerstonedev/sidecar/pull/15))
- `--pre-warm` options to `sidecar:deploy` and `sidecar:active` commands ([Commit](https://github.com/hammerstonedev/sidecar/commit/4794e6d4bfc5ddb4976c4686939ca1ee0c0ae979))
- `latestVersionHasAlias` method to the LambdaClient ([Commit](https://github.com/hammerstonedev/sidecar/commit/a54f4e59aef9bfeac57ced7fb50b0c25ff268ab9))

### Changed
- Warming is now opt-in. 0 instances are configured by default. ([Commit](https://github.com/hammerstonedev/sidecar/commit/ba53467368bcb253034fdbae7726fb0916b28de2))
- Moved some methods into the Sidecar\LambdaClient ([#15](https://github.com/hammerstonedev/sidecar/pull/15))
- Break out logging & environment concerns from the Labmda Client. ([Commit](https://github.com/hammerstonedev/sidecar/commit/20e368c9773c4aae2262021c7682cf72737af270))
- Break out logging & environment concerns from the Lambda Client. ([Commit](https://github.com/hammerstonedev/sidecar/commit/20e368c9773c4aae2262021c7682cf72737af270))

### Fixed
- Allow spacing in `APP_NAME` [#17](https://github.com/hammerstonedev/sidecar/pull/17)
Expand Down
153 changes: 40 additions & 113 deletions docs/configuration.md
Original file line number Diff line number Diff line change
@@ -1,31 +1,35 @@

# Configuring Sidecar

## Configuring AWS
After running `php artisan sidecar:install`, you should have a `sidecar.php` file in your `config` folder.

There are several configuration options in that file, which we'll cover in this section.

## AWS Credentials

Sidecar requires a few very specific things be set up in your AWS in order to have the proper permissions to deploy and execute your functions.

In order to save you from the frustration of AWS IAM, we have written a single, interactive command that can handle everything for you.
In order to save you from the frustration of using AWS IAM we have written a single, interactive command that can handle everything for you.

To get started, run the following command:

```text
```shell
php artisan sidecar:configure
```

The first thing it will do is guide you through creating a new AWS user, which it will then use to create everything else it needs.
The first thing it will do is guide you through creating a new AWS user in the web interface, which it will then use to create everything else it needs.

Note that this won't start any services, it just creates some policies in IAM.

This is the same method that Vapor uses: you provide it with Admin Access and then it configures itself.
This is the same general method that Laravel Vapor uses: you provide it with Admin Access and then it configures itself. Sidecar takes it a step further and provides you the option to self-destruct the admin keys once it has configured itself.

If you'd like to manually set everything up, take a look at the command to see exactly what it's doing, and you can recreate it in the IAM portal.

## Registering Functions

Each function that you make will need to be registered in the `functions` key of your `sidecar.php`

sidecar.php {.filename}
config/sidecar.php {.filename}
```php
return [
/*
Expand All @@ -35,45 +39,15 @@ return [
\App\Sidecar\OgImage::class,
\App\Sidecar\ProcessThumbnail::class,
],
// [tl! collapse-start closed]
/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
* *
* You are welcome to edit this configuration directly, or you can run *
* `php artisan sidecar:configure` for an interactive walk-through. *
* *
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */

/*
* Your AWS key. See CreateDeploymentUser::policy for the IAM policy.
*
* Unfortunately you cannot rely on the keys available in the Vapor
* runtime, as those do not have the right permissions.
*/
'aws_key' => env('SIDECAR_ACCESS_KEY_ID'),

/*
* Your AWS secret key.
*/
'aws_secret' => env('SIDECAR_SECRET_ACCESS_KEY'),

/*
* The region where your Lambdas will be deployed.
*/
'aws_region' => env('SIDECAR_REGION'),
];
```

/*
* The bucket that temporarily holds your function's ZIP files as they
* are deployed to Lambda. It must be the same region as your Lambdas.
*/
'aws_bucket' => env('SIDECAR_ARTIFACT_BUCKET_NAME'),
## Function Timeout & Memory

/*
* This is the execution role that your Lambdas will use.
*
* See CreateExecutionRole::policy for the IAM policy.
*/
'execution_role' => env('SIDECAR_EXECUTION_ROLE'),
The timeout and memory can be customized on a per-function basis, but if they aren't, the defaults from your `sidecar.php` file will be used.

```php
return [
/*
* The default timeout for your functions, in seconds.
* This can be overridden per function.
Expand All @@ -84,94 +58,47 @@ return [
* The default memory for your functions, in megabytes.
* This can be overridden per function.
*/
'memory' => env('SIDECAR_MEMORY', 512),

/*
* The base path for your package files. If you e.g. keep
* all your Lambda package files in your resource path,
* you may change the base path here.
*/
'package_base_path' => env('SIDECAR_PACKAGE_BASE_PATH', base_path()), // [tl! collapse-end]
'memory' => env('SIDECAR_MEMORY', 512),
];
```

## Default Settings

The timeout and memory can be customized on a per-function basis, but if they aren't, the defaults from your `sidecar.php` file will be used.

### Package Base Path
## Package Base Path

By default, all of your Lambda resources are going to be relative to the `base_path()` of your application. That means when you're defining your code packages, you'll use the root of your application as the starting point.

If all of your Lambda code lives in e.g. `resources/lambda`, then you can update your `package_base_path` to reflect that.

sidecar.php {.filename}
config/sidecar.php {.filename}
```php
return [
// [tl! collapse-start closed]
/*
* All of your function classes that you'd like to deploy go here.
*/
'functions' => [
\App\Sidecar\OgImage::class,
\App\Sidecar\ProcessThumbnail::class,
],

/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
* *
* You are welcome to edit this configuration directly, or you can run *
* `php artisan sidecar:configure` for an interactive walk-through. *
* *
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */

/*
* Your AWS key. See CreateDeploymentUser::policy for the IAM policy.
*
* Unfortunately you cannot rely on the keys available in the Vapor
* runtime, as those do not have the right permissions.
* The base path for your package files. If you e.g. keep
* all your Lambda package files in your resource path,
* you may change the base path here.
*/
'aws_key' => env('SIDECAR_ACCESS_KEY_ID'),
'package_base_path' => env('SIDECAR_PACKAGE_BASE_PATH', base_path()),
];
```

/*
* Your AWS secret key.
*/
'aws_secret' => env('SIDECAR_SECRET_ACCESS_KEY'),
This is also configurable on a per-function basis. To learn more about that, see the [Handlers & Packages](/functions/handlers-and-packages) section.

/*
* The region where your Lambdas will be deployed.
*/
'aws_region' => env('SIDECAR_REGION'),
## Environment

/*
* The bucket that temporarily holds your function's ZIP files as they
* are deployed to Lambda. It must be the same region as your Lambdas.
*/
'aws_bucket' => env('SIDECAR_ARTIFACT_BUCKET_NAME'),
Sidecar separates functions by environment so that your development, staging, and production functions do not overwrite each other.

/*
* This is the execution role that your Lambdas will use.
*
* See CreateExecutionRole::policy for the IAM policy.
*/
'execution_role' => env('SIDECAR_EXECUTION_ROLE'),
// [tl! collapse-end]
/*
* The default timeout for your functions, in seconds.
* This can be overridden per function.
*/
'timeout' => env('SIDECAR_TIMEOUT', 300),
By default, the environment name that Sidecar uses is your `APP_ENV` from your `.env` file. This usually works great for staging and production, but if you are working on a team, you'll have multiple people using an environment named `local`, potentially interfering with one another.

/*
* The default memory for your functions, in megabytes.
* This can be overridden per function.
*/
'memory' => env('SIDECAR_MEMORY', 512),
If you'd like to use something other than the `APP_ENV`, you can do so by providing a `SIDECAR_ENV` environment variable.

/*
* The base path for your package files. If you e.g. keep
* all your Lambda package files in your resource path,
* you may change the base path here.
```php
return [
/*
* Sidecar separates functions by environment. If you'd like to change
* your Sidecar environment without changing your entire application
* environment, you may do so here.
*/
'package_base_path' => env('SIDECAR_PACKAGE_BASE_PATH', base_path()),
'env' => env('SIDECAR_ENV', env('APP_ENV')),
];
```
```

To learn much more about environments and how to use them, see the [Environments](/environments) section.
40 changes: 40 additions & 0 deletions docs/environments.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,40 @@

# Environments

Sidecar functions are separated by environment, so that your local development functions don't overwrite your production functions. You can have as many environments as you please.

By default, Sidecar will use the environment from your Laravel application, which itself comes from the `APP_ENV` environment variable.

If you'd rather use a dedicated environment variable for Sidecar, you can use the `SIDECAR_ENV` variable.

```php
<?php

return [
/*
* Sidecar separates functions by environment. If you'd like to change
* your Sidecar environment without changing your entire application
* environment, you may do so here.
*/
'env' => env('SIDECAR_ENV', env('APP_ENV')),
];
```

This can be particularly useful when you're developing in a team. If everyone on your team has `APP_ENV=local` in their environment file, then it's likely that functions will inadvertently be overwritten by your teammates, which is both confusing and frustrating.

In this case, it would make sense to set your Sidecar environment to e.g. `SIDECAR_ENV=aaron_local`, `SIDECAR_ENV=sean_local`, etc.

This way Sean & Aaron have different environments and won't overwrite each other's work.

## Faking the Environment

If you need to deploy an environment other than the one you are in, you can override the environment from the config by passing an `--env` flag to the Deploy and Activate commands.

```shell
php artisan sidecar:deploy --env=production
php artisan sidecar:activate --env=production
```

This is useful when you want to build and deploy from either your local machine, your CI pipeline, or GitHub Actions, and then you want to activate as your Laravel application rolls out.

Head over to the [Deploying section](functions/deploying) to read more about activating & deploying your functions.
Loading

0 comments on commit d3ba88f

Please sign in to comment.