Skip to content

Documentation Corrections #23

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
May 23, 2017
Merged

Documentation Corrections #23

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
126 changes: 63 additions & 63 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,69 +4,66 @@
![LambdaCron](./lambda-cron-diagram.png "LambdaCron")

**LambdaCron** is a serverless cron tool. It provides a way to run scheduled tasks
on AWS cloud, all managed by a command line tool ([LambdaCron CLI](#lambdacron-cli)).
on the AWS cloud, all managed by a command line tool ([LambdaCron CLI](#lambdacron-cli)).

Tasks are scheduled using the same syntax for expressions as linux
Tasks are scheduled using the same syntax for expressions as Linux
[crontab](https://help.ubuntu.com/community/CronHowto).

**LambdaCron** offer 4 different type of task to run:
**LambdaCron** offers 4 different types of tasks:

* **Queue task**: send message to AWS SQS queue.
* **Lambda task**: invoke AWS lambda function.
* **Lambda task**: invoke AWS Lambda function.
* **Batch task**: submit AWS Batch job.
* **HTTP task**: send HTTP requests (GET & POST).

Tasks are defined in YAML files and are stored in a S3 bucket.

## LambdaCron CLI

**LambdaCron** provide a CLI tool that allow to manage your cron tasks from you localhost,
no need to access to AWS console.

Also it allows to run multiple environments with different settings. As many environments
as desired can be set up.
**LambdaCron** provides a CLI tool that allows management of your cron tasks without access
to the AWS Console. It also allows creation of multiple environments with different settings.

### Settings

Custom settings for environments are set in a YAML file located in user home, it must be
called: **~/.lambda-cron.yml**.
Custom settings for environments are set in a YAML-formatted configuration file located in the
user home directory, and must be named **~/.lambda-cron.yml**.

There are 3 levels of preferences for settings:

* Environment: Custom values for an specific environment.
* Global: Custom values that will have effect to all environments created.
* Default: Default values in case no custom values are specified (by environment or globally)

Highest level of preference is *Environment*, followed by *Global* and finally *Default*. Each option
Highest level of preference is *Environment*, followed by *Global* and finally *Default*. Each option
in the settings can set the value from different levels. Higher level of preference overwrite lower levels.

Settings are saved in a YAML file. Each environment is defined with a root key in the YAML,
global settings are identified with the key *global*.
Each environment is defined with a root key in the YAML, while global settings are identified with the
key *global*.

Options available:

#### bucket

Name of the bucket where lambda function code will be hosted and tasks stored.
Name of the bucket where Lambda function code will be hosted and tasks stored.

```yaml
bucket: 'my-custom-bucket-name'
```

You can use the pattern **{environment}** in the string for the bucket, it will
You can use the macro, **{environment}**, in the string for the bucket, and it will
be replaced by the environment name.

**Defualt**: lambda-cron-{environment}
**Default**: lambda-cron-{environment}

The bucket will have to folders:
The bucket will have two folders:

* code/
* tasks/

#### every (frequency)

Frequency with which the lambda function that evaluate tasks will run.
It indicates the frequency by **minutes OR hours** with an integer number.
Frequency at which the Lambda function will execute to run tasks.
It indicates the frequency in **minutes OR hours** with an integer number.
It is specified with one of the following parameters:

* minutes
Expand All @@ -77,13 +74,13 @@ every:
minutes: 5
```

**Defualt**: every hour.
**Default**: every hour.

More info for [frequency](#frequency)
More info for [frequency](#frequency).

#### alarm

Alarm can be set up using CloudWatch metrics. It uses following parameters:
Alarm can be set up using CloudWatch metrics. It uses the following parameters:

* enabled
* email (Required if alarm is enabled).
Expand All @@ -94,17 +91,17 @@ alarm:
email: my-mailing-list@email.com
```

**Defualt**: not enabled.
**Default**: disabled.

#### enabled

It allows to enabled/disabled the cron (CloudWatch event).
It enables/disables the cron (CloudWatch event).

```yaml
enabled: True
```

**Defualt**: enabled.
**Default**: enabled.

#### Example

Expand All @@ -115,7 +112,7 @@ global:
prod:
alarm:
enabled: True
email: dev-alerts@domain.com
email: prod-alerts@domain.com
every:
minutes: 5

Expand All @@ -134,7 +131,7 @@ The settings for each environment will be:
* bucket: my-project-cron-prod
* alarm:
* enabled: True
* email: dev-alerts@domain.com
* email: prod-alerts@domain.com
* every:
* minutes: 5

Expand All @@ -153,14 +150,16 @@ The settings for each environment will be:
* alarm:
* enabled: False
* email: ''

### Commands

**LambdaCron** CLI use [aws-cli](https://github.com/aws/aws-cli), every command
is translated into aws-cli command. AWS account should be configured for aws-cli.
LambdaCron CLI allow to specify different aws-cli profiles.
The **LambdaCron** CLI uses the [AWS CLI](https://github.com/aws/aws-cli), and translates
every command into an AWS CLI command. The AWS account used should be configured for AWS
CLI access. The LambdaCron CLI allows different AWS CLI
[profiles](http://docs.aws.amazon.com/cli/latest/userguide/cli-multiple-profiles.html) to
be specified.

Following is the list of commands available.
The following is the list of commands available.

#### create

Expand Down Expand Up @@ -192,7 +191,7 @@ Parameters:

#### stop

Disable LambdaCron, it won't run until it is enabled (#start command)
Disable LambdaCron, and it won't run until it is enabled (#start command) again.

Parameters:

Expand All @@ -201,7 +200,7 @@ Parameters:

#### invoke

Invoke lambda function cron manually
Invoke Lambda function cron manually.

Parameters:

Expand All @@ -210,20 +209,20 @@ Parameters:

#### delete

Delete **LambdaCron** environment from the AWS account
Delete **LambdaCron** environment from the AWS account.

Parameters:

* **--environment (-e)**: Environment to work with (string)
* **--delete-bucket**: Flag to indicate that the bucket must be deleted from S3 (optional)
* **--aws-profile (-a)**: AWS profile to use from aws-cli (string) (optional)

Note: To delete de bucket it must be empty.
Note: The bucket must be empty before it can be deleted.

#### upload-tasks

Upload tasks to S3 bucket to run with lambda-cron. It will sync the directory
with S3 deleting tasks have been deleted from the local directory.
Upload tasks to S3 bucket to be run with LambdaCron. It will sync the directory
with S3, including deleting tasks have been deleted from the local directory.

Parameters:

Expand All @@ -244,20 +243,21 @@ Parameters:

## Tasks

Tasks are defined in YAML files, each task in an independent file. Task must follow
the json schema provided in this repo: [schema](./lambda_cron/schema.json).
Tasks are defined in YAML files, with each task in an independent file. A task must follow
the JSON schema provided in this repo: [schema](./lambda_cron/schema.json).

All tasks must contains following keys and values:
All tasks must contain the following keys and values:

* **name**: task name
* **expression**: crontab expression
* **task**: task definition (customized for each type of tasks)

For each kind of task there a set of specific keys a values to set. Described bellow.
Each type of task has its own set of required keys as described in the following section.


### Queue task

It sends a message to a AWS SQS queue.
It sends a message to an AWS SQS queue.
The task definition must contains following keys:

* **type**: *queue*
Expand All @@ -284,10 +284,10 @@ All parameters of the function will be supported soon.
### Lambda task

It invokes an AWS lambda functions.
The task definition must contains following keys:
The task definition must contain the following keys:

* **type**: *lambda*
* **FunctionName**: Name of the lambda function to invoke (string)
* **FunctionName**: Name of the Lambda function to invoke (string)
* **InvokeArgs**: arguments to send (YAML/JSON)

``` yaml
Expand All @@ -301,12 +301,12 @@ task:
output: 's3://my-data-output/performance'
```

Function is invoked using [boto3 Lambda.Client.invoke_async](http://boto3.readthedocs.io/en/latest/reference/services/lambda.html#Lambda.Client.invoke_async)
The function is invoked using [boto3 Lambda.Client.invoke_async](http://boto3.readthedocs.io/en/latest/reference/services/lambda.html#Lambda.Client.invoke_async)

### Batch task

It submits AWS Batch Jobs.
The task definition must contains following keys:
It submits AWS Batch jobs.
The task definition must contain the following keys:

* **type**: *batch*
* **jobName**: name to assign to the job (string)
Expand All @@ -324,12 +324,12 @@ task:
```

It is a wrapper for [boto3 Batch.Client.submit_job](http://boto3.readthedocs.io/en/latest/reference/services/batch.html#Batch.Client.submit_job).
It means all parameters for the method can be set in the task definition.
All parameters for the method can be set in the task definition.

### HTTP task

It send and HTTP request (GET or POST).
The task definition must contains following keys:
It sends an HTTP request (GET or POST).
The task definition must contain the following keys:

* **type**: *http*
* **method**: http method (get | post)
Expand All @@ -348,24 +348,24 @@ task:
```

It is a wrapper over [Requests](http://docs.python-requests.org/en/master/).
All http methods will be supported soon.
All HTTP methods will be supported soon.

## Frequency

#### Execution time
#### Execution time
All tasks scheduled to run between the current event and the next event will be run immediately.

Example: LambdaCron runs every hour ('0 * * * *'), tasks '0 1 * * *' and '58 1 * * *' will run at the same time.

#### Task frequency
Lambda cron will execute a task at most once invocation. This can result in a task being run fewer times than it's cron expression implies.
#### Task frequency
LambdaCron will execute a task at most once for each invocation. This can result in a task being run fewer times than it's cron expression implies.

Example: If LambdaCron runs every hour ('0 * * * *'), a task '*/15 * * * *' will only run once an hour. If LambdaCron runs every minute ('* * * * *'), a task '*/15 * * * *' will only run four times an hour.
Example: If LambdaCron runs every hour ('0 * * * *'), a task '*/15 * * * *' will only run once an hour. If LambdaCron runs every minute ('* * * * *'), a task '*/15 * * * *' will only run four times an hour. You can set up LambdaCron to run more frequently than an hour if you need a task to be run more frequently.

#### Frequecy and Precision

Events are based on [AWS CloudWatch Events](http://docs.aws.amazon.com/AmazonCloudWatch/latest/events/WhatIsCloudWatchEvents.html).
You can read in following [documentation](http://docs.aws.amazon.com/AmazonCloudWatch/latest/events/ScheduledEvents.html):
You can learn about them in the [Scheduled Events documentation](http://docs.aws.amazon.com/AmazonCloudWatch/latest/events/ScheduledEvents.html):

* "The finest resolution using a Cron expression is a minute"
* "Your scheduled rule is triggered within that minute, but not on the precise 0th second"
Expand All @@ -392,7 +392,7 @@ Be aware of this.
$ pip install lambda-cron
```

### Usage
### Usage

Create your first environment (called 'test') with default settings:

Expand All @@ -403,7 +403,7 @@ $ lambda-cron create --environment=test --create-bucket
If you want to set some custom settings, create the setting file in the home
directory of the user who is running the tool.

* ~/.lambda-cron.yml
* `~/.lambda-cron.yml`

For help:

Expand All @@ -419,7 +419,7 @@ $ lambda-cron create --help

## Development

To start working with **LambdaCron** you should clone the project, create a
To start working with **LambdaCron** you should clone the project, create a
virtualenv (optional) and install dependencies:

``` bash
Expand All @@ -433,8 +433,8 @@ $ ./lambda_cron/lambda-cron --help

## Contributing

Contributions are welcome. You can find open issues with some features and
Contributions are welcome. You can find open issues with some features and
improvements that would be good to have in **LambdaCron**.

Before contribute we encourage to take a look of following
Before contribute we encourage to take a look of following
[tips provided by GitHub](https://guides.github.com/activities/contributing-to-open-source/)