Skip to content

Commit 0bae9d4

Browse files
efekarakusefekarakus
authored
docs(site): add scheduled job manifest documentation (#1553)
_By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice._
1 parent c8f0afc commit 0bae9d4

File tree

4 files changed

+140
-5
lines changed

4 files changed

+140
-5
lines changed

‎mkdocs.yml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,7 @@ nav:
2626
- Overview: docs/manifest/overview.md
2727
- Load Balanced Web Service: docs/manifest/lb-web-service.md
2828
- Backend Service: docs/manifest/backend-service.md
29+
- Scheduled Job: docs/manifest/scheduled-job.md
2930
- Pipeline: docs/manifest/pipeline.md
3031
- Developing:
3132
- Environment Variables: docs/developing/environment-variables.md

‎site/content/docs/manifest/backend-service.md

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@ image:
1111
build: ./api/Dockerfile
1212
# Or instead of building, you can specify an existing image name.
1313
location: aws_account_id.dkr.ecr.region.amazonaws.com/my-svc:tag
14-
# Port exposed through your container to route traffic to it.
14+
# Optional. Port exposed through your container to route traffic to it.
1515
port: 8080
1616

1717
#Optional. Configuration for your container healthcheck.
@@ -83,7 +83,8 @@ Instead of building a container from a Dockerfile, you can specify an existing i
8383
The `location` field follows the same definition as the [`image` parameter](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task_definition_parameters.html#container_definition_image) in the Amazon ECS task definition.
8484

8585
<span class="parent-field">image.</span><a id="image-port" href="#image-port" class="field">`port`</a> <span class="type">Integer</span>
86-
The port exposed in your Dockerfile. Copilot should parse this value for you from your `EXPOSE` instruction.
86+
The port exposed in your Dockerfile. Copilot should parse this value for you from your `EXPOSE` instruction.
87+
If you don't need your backend service to accept requests from other services you can omit this field.
8788

8889
<span class="parent-field">image.</span><a id="image-healthcheck" href="#image-healthcheck" class="field">`healthcheck`</a> <span class="type">Map</span>
8990
Optional configuration for container health checks.

‎site/content/docs/manifest/overview.md

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,8 @@
11
# Manifest
22

3-
The AWS Copilot CLI manifests describe a service’s architecture as infrastructure-as-code.
3+
The AWS Copilot CLI manifests describe a service’s or job's architecture as infrastructure-as-code.
44

5-
It is a file generated from `copilot init` or `copilot svc init` that gets converted to a AWS CloudFormation template. Unlike raw CloudFormation templates, the manifest allows you to focus on the most common settings for the _architecture_ of your service and not the individual resources.
5+
It is a file generated from `copilot init`, `copilot svc init`, or `copilot job init` that gets converted to a AWS CloudFormation template.
6+
Unlike raw CloudFormation templates, the manifest allows you to focus on the most common settings for the _architecture_ of your service or job and not the individual resources.
67

7-
Manifest files are stored under `copilot/<your service name>/manifest.yml`.
8+
Manifest files are stored under `copilot/<your service or job name>/manifest.yml`.

‎site/content/docs/manifest/scheduled-job.md

Lines changed: 132 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,132 @@
1+
List of all available properties for a `'Scheduled Job'` manifest.
2+
```yaml
3+
# Your job name will be used in naming your resources like log groups, ECS Tasks, etc.
4+
name: report-generator
5+
# The type of job that you're running.
6+
type: Scheduled Job
7+
8+
image:
9+
# Path to your service's Dockerfile.
10+
build: ./Dockerfile
11+
# Or instead of building, you can specify an existing image name.
12+
location: aws_account_id.dkr.ecr.region.amazonaws.com/my-svc:tag
13+
14+
on:
15+
# The scheduled trigger for your job. You can specify a Unix cron schedule or keyword (@weekly) or a rate (@every 1h30m)
16+
17+
# AWS Schedule Expressions are also accepted: https://docs.aws.amazon.com/AmazonCloudWatch/latest/events/ScheduledEvents.html
18+
schedule: @daily
19+
20+
cpu: 256 # Number of CPU units for the task.
21+
memory: 512 # Amount of memory in MiB used by the task.
22+
retries: 3 # Optional. The number of times to retry the job before failing.
23+
timeout: 1h # Optional. The timeout after which to stop the job if it's still running. You can use the units (h, m, s).
24+
25+
variables: # Optional. Pass environment variables as key value pairs.
26+
LOG_LEVEL: info
27+
28+
secrets: # Optional. Pass secrets from AWS Systems Manager (SSM) Parameter Store.
29+
GITHUB_TOKEN: GITHUB_TOKEN # The key is the name of the environment variable, the value is the name of the SSM parameter.
30+
31+
environments: # Optional. You can override any of the values defined above by environment.
32+
prod:
33+
cpu: 512
34+
```
35+
36+
<a id="name" href="#name" class="field">`name`</a> <span class="type">String</span>
37+
The name of your job.
38+
39+
<div class="separator"></div>
40+
41+
<a id="type" href="#type" class="field">`type`</a> <span class="type">String</span>
42+
The architecture type for your job.
43+
Currently, Copilot only supports the "Scheduled Job" type for tasks that are triggered either on a fixed schedule or periodically.
44+
45+
<div class="separator"></div>
46+
47+
<a id="image" href="#image" class="field">`image`</a> <span class="type">Map</span>
48+
The image section contains parameters relating to the Docker build configuration.
49+
50+
<span class="parent-field">image.</span><a id="image-build" href="#image-build" class="field">`build`</a> <span class="type">String or Map</span>
51+
If you specify a string, Copilot interprets it as the path to your Dockerfile. It will assume that the dirname of the string you specify should be the build context. The manifest:
52+
```yaml
53+
image:
54+
build: path/to/dockerfile
55+
```
56+
will result in the following call to docker build: `$ docker build --file path/to/dockerfile path/to`
57+
58+
You can also specify build as a map:
59+
```yaml
60+
image:
61+
build:
62+
dockerfile: path/to/dockerfile
63+
context: context/dir
64+
args:
65+
key: value
66+
```
67+
In this case, Copilot will use the context directory you specified and convert the key-value pairs under args to --build-arg overrides. The equivalent docker build call will be: `$ docker build --file path/to/dockerfile --build-arg key=value context/dir`.
68+
69+
You can omit fields and Copilot will do its best to understand what you mean. For example, if you specify `context` but not `dockerfile`, Copilot will run Docker in the context directory and assume that your Dockerfile is named "Dockerfile." If you specify `dockerfile` but no `context`, Copilot assumes you want to run Docker in the directory that contains `dockerfile`.
70+
71+
All paths are relative to your workspace root.
72+
73+
<span class="parent-field">image.</span><a id="image-location" href="#image-location" class="field">`location`</a> <span class="type">String</span>
74+
Instead of building a container from a Dockerfile, you can specify an existing image name. Mutually exclusive with [`image.build`](#image-build).
75+
The `location` field follows the same definition as the [`image` parameter](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task_definition_parameters.html#container_definition_image) in the Amazon ECS task definition.
76+
77+
<div class="separator"></div>
78+
79+
<a id="on" href="#on" class="field">`on`</a> <span class="type">Map</span>
80+
The configuration for the event that triggers your job.
81+
82+
<span class="parent-field">on.</span><a id="on-schedule" href="#on-schedule" class="field">`schedule`</a> <span class="type">String</span>
83+
You can specify a rate to periodically trigger your job, supported rates:
84+
85+
* `"@yearly"`
86+
* `"@monthly"`
87+
* `"@weekly"`
88+
* `"@daily"`
89+
* `"@hourly"`
90+
* `"@every {duration}"` (For example, "1m", "5m")
91+
* `"rate({duration})"` based on CloudWatch's [rate expressions](https://docs.aws.amazon.com/AmazonCloudWatch/latest/events/ScheduledEvents.html#RateExpressions)
92+
93+
Alternatively, you can specify a cron schedule if you'd like to trigger the job at a specific time:
94+
95+
* `"* * * * *"` based on the standard [cron format](https://en.wikipedia.org/wiki/Cron#Overview).
96+
* `"cron({fields})"` based on CloudWatch's [cron expressions](https://docs.aws.amazon.com/AmazonCloudWatch/latest/events/ScheduledEvents.html#CronExpressions) with six fields.
97+
98+
<div class="separator"></div>
99+
100+
<a id="cpu" href="#cpu" class="field">`cpu`</a> <span class="type">Integer</span>
101+
Number of CPU units for the task. See the [Amazon ECS docs](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task-cpu-memory-error.html) for valid CPU values.
102+
103+
<div class="separator"></div>
104+
105+
<a id="memory" href="#memory" class="field">`memory`</a> <span class="type">Integer</span>
106+
Amount of memory in MiB used by the task. See the [Amazon ECS docs](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task-cpu-memory-error.html) for valid memory values.
107+
108+
<div class="separator"></div>
109+
110+
<a id="retries" href="#retries" class="field">`retries`</a> <span class="type">Integer</span>
111+
The number of times to retry the job before failing.
112+
113+
<div class="separator"></div>
114+
115+
<a id="timeout" href="#timeout" class="field">`timeout`</a> <span class="type">Duration</span>
116+
How long the job should run before it aborts and fails. You can use the units: `h`, `m`, or `s`.
117+
118+
<div class="separator"></div>
119+
120+
<a id="variables" href="#variables" class="field">`variables`</a> <span class="type">Map</span>
121+
Key-value pairs that represents environment variables that will be passed to your job. Copilot will include a number of environment variables by default for you.
122+
123+
<div class="separator"></div>
124+
125+
<a id="secrets" href="#secrets" class="field">`secrets`</a> <span class="type">Map</span>
126+
Key-value pairs that represents secret values from [AWS Systems Manager Parameter Store](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-parameter-store.html) that will passed to your job as environment variables securely.
127+
128+
<div class="separator"></div>
129+
130+
<a id="environments" href="#environments" class="field">`environments`</a> <span class="type">Map</span>
131+
The environment section lets you overwrite any value in your manifest based on the environment you're in.
132+
In the example manifest above, we're overriding the cpu parameter so that our production container is more performant.

0 commit comments

Comments
 (0)