Skip to content
This repository was archived by the owner on Aug 7, 2025. It is now read-only.

Commit 00ea9be

Browse files
viren-nadkarniviren-nadkarni
committed
Update
1 parent 562b13f commit 00ea9be

File tree

1 file changed

+207
-29
lines changed
  • content/en/user-guide/aws/codepipeline

1 file changed

+207
-29
lines changed

‎content/en/user-guide/aws/codepipeline/index.md‎

Lines changed: 207 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -17,15 +17,14 @@ The available operations can be found on the [API coverage](https://docs.localst
1717

1818
## Getting started
1919

20-
This guide is for users that are new to IoT and assumes a basic knowledge of the AWS CLI and LocalStack [`awslocal`](https://github.com/localstack/awscli-local) wrapper.
20+
In this guide, we will create a simple pipeline that fetches an object from an S3 bucket and uploads it to a different S3 bucket.
21+
It is for users that are new to CodePipeline and have a basic knowledge of the AWS CLI and the [`awslocal`](https://github.com/localstack/awscli-local) wrapper.
2122

2223
Start LocalStack using your preferred method.
2324

24-
In this guide, we will create a simple pipeline that fetches an object from an S3 bucket and uploads it to a different S3 bucket.
25-
2625
### Create prerequisite buckets
2726

28-
Start by creating the S3 buckets that will serve as the source and target.
27+
Begin by creating the S3 buckets that will serve as the source and target.
2928

3029
{{< command >}}
3130
$ awslocal s3 mb s3://source-bucket
@@ -66,7 +65,7 @@ Depending on the specifics of the declaration, CodePipeline pipelines need acces
6665
In this case we want our pipeline to retrieve and upload files to S3.
6766
This requires a properly configured IAM role that our pipeline can assume.
6867

69-
Create the role as follows:
68+
Create the role and make note of the role ARN:
7069

7170
```json
7271
# role.json
@@ -85,7 +84,10 @@ Create the role as follows:
8584
```
8685

8786
{{< command >}}
88-
$ awslocal iam create-role --role-name role --assume-role-policy-document file://role.json
87+
$ awslocal iam create-role --role-name role --assume-role-policy-document file://role.json | jq .Role.Arn
88+
<disable-copy>
89+
"arn:aws:iam::000000000000:role/role"
90+
</disable-copy>
8991
{{< /command >}}
9092

9193
Now add a permissions policy to this role that permits read and write access to S3.
@@ -98,7 +100,7 @@ Now add a permissions policy to this role that permits read and write access to
98100
{
99101
"Effect": "Allow",
100102
"Action": [
101-
"s3:*",
103+
"s3:*"
102104
],
103105
"Resource": "*"
104106
},
@@ -114,7 +116,7 @@ Now add a permissions policy to this role that permits read and write access to
114116
```
115117

116118
The permissions in the above example policy are relatively broad.
117-
You might want to use a more focused policy for better security.
119+
You might want to use a more focused policy for better security on production systems.
118120

119121
{{< command >}}
120122
$ awslocal iam put-role-policy --role-name role --policy-name policy --policy-document file://policy.json
@@ -124,15 +126,25 @@ $ awslocal iam put-role-policy --role-name role --policy-name policy --policy-do
124126

125127
Now we can turn our attention to the pipeline declaration.
126128

127-
```json
129+
A pipeline declaration is used to define the structure of actions and stages to be performed.
130+
The following pipeline defines two stages with one action each.
131+
There is a source action which retrieves a file from an S3 bucket and marks it as the output.
132+
The output is placed in the intermediate bucket until it is picked up by the action in the second stage.
133+
This is a deploy action which uploads the file to the target bucket.
134+
135+
Pay special attention to `roleArn`, `artifactStore.location` as well as `S3Bucket`, `S3ObjectKey`, and `BucketName`.
136+
These correspond to the resources we created earlier.
137+
138+
```json {hl_lines=[6,9,26,27,52]}
139+
# declaration.json
128140
{
129141
"name": "pipeline",
130142
"executionMode": "SUPERSEDED",
131143
"pipelineType": "V1",
132-
"roleArn": "<TODO>",
144+
"roleArn": "arn:aws:iam::000000000000:role/role",
133145
"artifactStore": {
134146
"type": "S3",
135-
"location": "<TODO>"
147+
"location": "artifact-store-bucket"
136148
},
137149
"version": 1,
138150
"stages": [
@@ -149,13 +161,13 @@ Now we can turn our attention to the pipeline declaration.
149161
},
150162
"runOrder": 1,
151163
"configuration": {
152-
"S3Bucket": "<TODO>",
153-
"S3ObjectKey": "<TODO>",
164+
"S3Bucket": "source-bucket",
165+
"S3ObjectKey": "file",
154166
"PollForSourceChanges": "false"
155167
},
156168
"outputArtifacts": [
157169
{
158-
"name": "intermediate-artifact-file"
170+
"name": "intermediate-file"
159171
}
160172
],
161173
"inputArtifacts": []
@@ -175,13 +187,13 @@ Now we can turn our attention to the pipeline declaration.
175187
},
176188
"runOrder": 1,
177189
"configuration": {
178-
"BucketName": "<TODO>",
190+
"BucketName": "target-bucket",
179191
"Extract": "false",
180-
"ObjectKey": "output-artifact-file"
192+
"ObjectKey": "output-file"
181193
},
182194
"inputArtifacts": [
183195
{
184-
"name": "intermediate-artifact-file"
196+
"name": "intermediate-file"
185197
}
186198
],
187199
"outputArtifacts": []
@@ -192,37 +204,203 @@ Now we can turn our attention to the pipeline declaration.
192204
}
193205
```
194206

195-
## Tips
207+
Create the pipeline using the following command:
196208

197-
- Use `runOrder`
209+
{{< command >}}
210+
$ awslocal codepipeline create-pipeline --pipeline file://./declaration.json
211+
{{< /command >}}
198212

213+
### Verify pipeline execution
199214

200-
## Actions
215+
A 'pipeline execution' is an instance of a pipeline in running or finished state.
201216

202-
CodePipeline on LocalStack supports the following actions:
217+
The CreatePipeline operation we ran earlier started a pipeline execution.
218+
This can be confirmed using:
203219

204-
### S3 Source
220+
{{< command >}}
221+
$ awslocal codepipeline list-pipeline-executions --pipeline-name pipeline
222+
<disable-copy>
223+
{
224+
"pipelineExecutionSummaries": [
225+
{
226+
"pipelineExecutionId": "37e8eb2e-0ed9-447a-a016-8dbbd796bfe7",
227+
"status": "Succeeded",
228+
"startTime": 1745486647.138571,
229+
"lastUpdateTime": 1745486648.290341,
230+
"trigger": {
231+
"triggerType": "CreatePipeline"
232+
},
233+
"executionMode": "SUPERSEDED"
234+
}
235+
]
236+
}
237+
</disable-copy>
238+
{{< /command >}}
205239

206-
The [S3 Source](https://docs.aws.amazon.com/codepipeline/latest/userguide/action-reference-S3.html) action is used to specify an S3 bucket object as input to the pipeline.
240+
Note the `trigger.triggerType` field specifies what initiated the pipeline execution.
241+
Currently in LocalStack, only two triggers are implemented: `CreatePipeline` and `StartPipelineExecution`.
207242

208-
### S3 Deploy
243+
The above pipeline execution was successful.
244+
This means that we can retrieve the `output-file` object from the `target-bucket` S3 bucket.
209245

210-
The [S3 Deploy](https://docs.aws.amazon.com/codepipeline/latest/userguide/action-reference-S3Deploy.html) action is used to upload artifacts to a given S3 bucket as the output of the pipeline.
246+
{{< command >}}
247+
$ awslocal s3 cp s3://target-bucket/output-file output-file
248+
<disable-copy>
249+
download: s3://target-bucket/output-file to ./output-file
250+
</disable-copy>
251+
{{< /command >}}
252+
253+
To verify that it is the same file as the original input:
254+
255+
{{< command >}}
256+
$ cat output-file
257+
<disable-copy>
258+
Hello LocalStack!
259+
</disable-copy>
260+
{{< /command >}}
261+
262+
### Examine action executions
263+
264+
Using the [ListActionExecutions](https://docs.aws.amazon.com/codepipeline/latest/APIReference/API_ListPipelineExecutions.html), detailed information about each action execution such as inputs and outputs can be retrieved.
265+
This is useful when debugging the pipeline.
266+
267+
{{< command >}}
268+
$ awslocal codepipeline list-action-executions --pipeline-name pipeline
269+
<disable-copy>
270+
{
271+
"actionExecutionDetails": [
272+
{
273+
"pipelineExecutionId": "37e8eb2e-0ed9-447a-a016-8dbbd796bfe7",
274+
"actionExecutionId": "e38716df-645e-43ce-9597-104735c7f92c",
275+
"pipelineVersion": 1,
276+
"stageName": "stage2",
277+
"actionName": "action1",
278+
"startTime": 1745486647.269867,
279+
"lastUpdateTime": 1745486647.289813,
280+
"status": "Succeeded",
281+
"input": {
282+
"actionTypeId": {
283+
"category": "Deploy",
284+
"owner": "AWS",
285+
"provider": "S3",
286+
"version": "1"
287+
},
288+
"configuration": {
289+
"BucketName": "target-bucket",
290+
"Extract": "false",
291+
"ObjectKey": "output-file"
292+
},
293+
"resolvedConfiguration": {
294+
"BucketName": "target-bucket",
295+
"Extract": "false",
296+
"ObjectKey": "output-file"
297+
},
298+
"region": "eu-central-1",
299+
"inputArtifacts": [
300+
{
301+
"name": "intermediate-file",
302+
"s3location": {
303+
"bucket": "artifact-store-bucket",
304+
"key": "pipeline/intermediate-file/01410aa4.zip"
305+
}
306+
}
307+
]
308+
},
309+
"output": {
310+
"outputArtifacts": [],
311+
"executionResult": {
312+
"externalExecutionId": "bcff0781",
313+
"externalExecutionSummary": "Deployment Succeeded"
314+
},
315+
"outputVariables": {}
316+
}
317+
},
318+
{
319+
"pipelineExecutionId": "37e8eb2e-0ed9-447a-a016-8dbbd796bfe7",
320+
"actionExecutionId": "ae99095a-1d43-46ee-8a48-c72b6d60021e",
321+
"pipelineVersion": 1,
322+
"stageName": "stage1",
323+
"actionName": "action1",
324+
...
325+
</disable-copy>
326+
{{< /command >}}
327+
328+
## Pipelines
329+
330+
The operations [CreatePipeline](https://docs.aws.amazon.com/codepipeline/latest/APIReference/API_CreatePipeline.html), [GetPipeline](https://docs.aws.amazon.com/codepipeline/latest/APIReference/API_GetPipeline.html), [UpdatePipeline](https://docs.aws.amazon.com/codepipeline/latest/APIReference/API_UpdatePipeline.html), [ListPipelines](https://docs.aws.amazon.com/codepipeline/latest/APIReference/API_ListPipelines.html), [DeletePipeline](https://docs.aws.amazon.com/codepipeline/latest/APIReference/API_DeletePipeline.html) are used to manage pipeline declarations.
331+
332+
Pipeline executions can be managed with [StartPipelineExecution](https://docs.aws.amazon.com/codepipeline/latest/APIReference/API_StartPipelineExecution.html), [GetPipelineExecution](https://docs.aws.amazon.com/codepipeline/latest/APIReference/API_GetPipelineExecution.html), [ListPipelineExecutions](https://docs.aws.amazon.com/codepipeline/latest/APIReference/API_ListPipelineExecutions.html) and [StopPipelineExecutions](https://docs.aws.amazon.com/codepipeline/latest/APIReference/API_StopPipelineExecution.html).
333+
334+
Action executions can be inspected using the [ListActionExecutions](https://docs.aws.amazon.com/codepipeline/latest/APIReference/API_ListPipelineExecutions.html) operation.
335+
336+
LocalStack supports emulation for V1 pipelines.
337+
V2 pipelines are only created as mocks.
338+
339+
You can use `runOrder`
340+
341+
When stopping pipeline executions with StopPipelineExecution, the stop and abandon method is not supported.
342+
Setting the `abandon` flag will have no impact.
343+
This is because LocalStack uses threads as the underlying mechanism to simulate pipelines, and threads can not be cleanly preempted.
344+
345+
### Tagging pipelines
346+
347+
LocalStack also supports [resources tagging for pipelines](https://docs.aws.amazon.com/codepipeline/latest/userguide/pipelines-tag.html) using the [TagResource](https://docs.aws.amazon.com/codepipeline/latest/APIReference/API_TagResource.html), [UntagResource](https://docs.aws.amazon.com/codepipeline/latest/APIReference/API_UntagResource.html) and [ListTagsForResource](https://docs.aws.amazon.com/codepipeline/latest/APIReference/API_ListTagsForResource.html) operations.
348+
349+
{{< command >}}
350+
$ awslocal codepipeline tag-resource \
351+
--resource-arn arn:aws:codepipeline:eu-central-1:000000000000:pipeline \
352+
--tags key=purpose,value=tutorial
353+
354+
$ awslocal codepipeline list-tags-for-resource \
355+
--resource-arn arn:aws:codepipeline:eu-central-1:000000000000:pipeline
356+
{
357+
"tags": [
358+
{
359+
"key": "purpose",
360+
"value": "tutorial"
361+
}
362+
]
363+
}
364+
365+
$ awslocal codepipeline untag-resource \
366+
--resource-arn arn:aws:codepipeline:eu-central-1:000000000000:pipeline \
367+
--tag-keys purpose
368+
{{< /command >}}
369+
370+
371+
## Stages
372+
373+
## Variables
374+
375+
## Actions
376+
377+
CodePipeline on LocalStack supports the following actions:
378+
379+
### CodeBuild Source and Test
380+
381+
The [CodeBuild Source and Test](https://docs.aws.amazon.com/codepipeline/latest/userguide/action-reference-CodeBuild.html) action can be used to start a CodeBuild container and run the given buildspec.
211382

212383
### CodeConnections Source
213384

214385
The [CodeConnections Source](https://docs.aws.amazon.com/codepipeline/latest/userguide/action-reference-CodestarConnectionSource.html) action is used to specify a VCS repo as the input to the pipeline.
215386

216-
Currently LocalStack supports integration with [GitHub](https://github.com/).
387+
LocalStack supports integration only with [GitHub](https://github.com/) at this time.
217388
Please set the environment configuration option `CODEPIPELINE_GH_TOKEN` with the GitHub Personal Access Token to be able to fetch private repositories.
218389

219-
### CodeBuild Source and Test
390+
### S3 Deploy
220391

221-
The [CodeBuild Source and Test](https://docs.aws.amazon.com/codepipeline/latest/userguide/action-reference-CodeBuild.html) action can be used to start a CodeBuild container and run the given buildspec.
392+
The [S3 Deploy](https://docs.aws.amazon.com/codepipeline/latest/userguide/action-reference-S3Deploy.html) action is used to upload artifacts to a given S3 bucket as the output of the pipeline.
393+
394+
### S3 Source
395+
396+
The [S3 Source](https://docs.aws.amazon.com/codepipeline/latest/userguide/action-reference-S3.html) action is used to specify an S3 bucket object as input to the pipeline.
222397

223398
## Limitations
224399

225-
- [V2 pipeline types](https://docs.aws.amazon.com/codepipeline/latest/userguide/pipeline-types-planning.html) are not supported.
400+
- Emulation for [V2 pipeline types](https://docs.aws.amazon.com/codepipeline/latest/userguide/pipeline-types-planning.html) is not supported. They will be created as mocks only.
226401
- [Rollbacks and stage retries](https://docs.aws.amazon.com/codepipeline/latest/userguide/pipelines-stages.html) are not available.
227402
- [Triggers](https://docs.aws.amazon.com/codepipeline/latest/userguide/pipelines-triggers.html) are not implemented.
228403
Pipelines are executed only when [CreatePipeline](https://docs.aws.amazon.com/codepipeline/latest/APIReference/API_CreatePipeline.html) and [StartPipelineExecution](https://docs.aws.amazon.com/codepipeline/latest/APIReference/API_StartPipelineExecution.html) are invoked.
404+
- [Execution mode behaviours](https://docs.aws.amazon.com/codepipeline/latest/userguide/concepts-how-it-works.html#concepts-how-it-works-executions) are not implemented. Therefore parallel pipeline executions will not lead to stage locks and waits.
405+
- [Stage transition controls](https://docs.aws.amazon.com/codepipeline/latest/userguide/transitions.html) are not implemented.
406+
- [Manual approval action](https://docs.aws.amazon.com/codepipeline/latest/userguide/approvals-action-add.html) and [PutApprovalResult](https://docs.aws.amazon.com/codepipeline/latest/APIReference/API_PutApprovalResult.html) operation is not available.

0 commit comments

Comments
 (0)