This plugins adds Jenkins pipeline steps to interact with the AWS API.
- Invalidating CloudFront distributions
- Creating, updating and deleting CloudFormation stacks
- Up- and downloading files to/from S3
see the changelog for release information
the withAWS
step provides authorization for the nested steps.
You can provide region and profile information or let Jenkins
assume a role in another or the same AWS account.
You can mix all parameters in one withAWS
block.
Set region information:
withAWS(region:'eu-west-1') {
// do something
}
Use Jenkins UsernamePassword credentials information (Username: AccessKeyId, Password: SecretAccessKey):
withAWS(credentials:'nameOfSystemCredentials') {
// do something
}
Use profile information from ~/.aws/config
:
withAWS(profile:'myProfile') {
// do something
}
Assume role information (account is optional - uses current account as default, externalId is optional):
withAWS(role:'admin', roleAccount:'123456789012', externalId: 'my-external-id') {
// do something
}
Print current AWS identity information to the log.
awsIdentity()
Invalidate given paths in CloudFront distribution.
cfInvalidate(distribution:'someDistributionId', paths:['/*'])
Upload a file/folder from the workspace to an S3 bucket.
If the file
parameter denotes a directory, the complete directory including all subfolders will be uploaded.
s3Upload(file:'file.txt', bucket:'my-bucket', path:'path/to/target/file.txt')
s3Upload(file:'someFolder', bucket:'my-bucket', path:'path/to/targetFolder/')
Download a file/folder from S3 to the local workspace.
Set optional parameter force
to true
to overwrite existing file in workspace.
If the path
ends with a /
the complete virtual directory will be downloaded.
s3Download(file:'file.txt', bucket:'my-bucket', path:'path/to/source/file.txt', force:true)
s3Download(file:'targetFolder/', bucket:'my-bucket', path:'path/to/sourceFolder/', force:true)
Delete a file/folder from S3. If the path ends in a "/", then the path will be interpreted to be a folder, and all of its contents will be removed.
s3Delete(bucket:'my-bucket', path:'path/to/source/file.txt')
s3Delete(bucket:'my-bucket', path:'path/to/sourceFolder/')
This provides a way to query the files/folders in the S3 bucket, analogous to the findFiles
step provided by "pipeline-utility-steps-plugin".
If specified, the path
limits the scope of the operation to that folder only.
The glob
parameter tells s3FindFiles
what to look for. This can be a file name, a full path to a file, or a standard glob ("*", "*.ext", "path/**/file.ext", etc.).
If you do not specify path
, then it will default to the root of the bucket.
The path is assumed to be a folder; you do not need to end it with a "/", but it is okay if you do.
The path
property of the results will be relative to this value.
This works by enumerating every file/folder in the S3 bucket under path
and then performing glob matching.
When possible, you should use path
to limit the search space for efficiency purposes.
If you do not specify glob
, then it will default to "*".
By default, this will return both files and folders.
To only return files, set the onlyFiles
parameter to true
.
files = s3FindFiles(bucket:'my-bucket')
files = s3FindFiles(bucket:'my-bucket', glob:'path/to/targetFolder/file.ext')
files = s3FindFiles(bucket:'my-bucket', path:'path/to/targetFolder/', glob:'file.ext')
files = s3FindFiles(bucket:'my-bucket', path:'path/to/targetFolder/', glob:'*.ext')
files = s3FindFiles(bucket:'my-bucket', path:'path/', glob:'**/file.ext')
s3FindFiles
returns an array of FileWrapper
objects exactly identical to those returned by findFiles
.
Each FileWrapper
object has the following properties:
name
: the filename portion of the path (for "path/to/my/file.ext", this would be "file.ext")path
: the full path of the file, relative to thepath
specified (forpath
="path/to/", this property of the file "path/to/my/file.ext" would be "my/file.ext")directory
: true if this is a directory; false otherwiselength
: the length of the file (this is always "0" for directories)lastModified
: the last modification timestamp, in milliseconds since the Unix epoch (this is always "0" for directories)
When used in a string context, a FileWrapper
object returns the value of its path
property.
Validates the given CloudFormation template.
cfnValidate(file:'template.yaml')
Create or update the given CloudFormation stack using the given template from the workspace.
You can specify an optional list of parameters.
You can also specify a list of keepParams
of parameters which will use the previous value on stack updates.
Using timeoutInMinutes
you can specify the amount of time that can pass before the stack status becomes CREATE_FAILED and the stack gets rolled back.
Due to limitations in the AWS API, this only applies to stack creation.
If you have many parameters you can specify a paramsFile
containing the parameters. The format is either a standard
JSON file like with the cli or a YAML file for the cfn-params command line utility.
Additionally you can specify a list of tags that are set on the stack and all resources created by CloudFormation. The step returns the outputs of the stack as a map.
To prevent running into rate limiting on the AWS API you can change the default polling interval of 1000 ms using the parameter pollIntervall
. Using the value 0
disables event printing.
def outputs = cfnUpdate(stack:'my-stack', file:'template.yaml', params:['InstanceType=t2.nano'], keepParams:['Version'], timeoutInMinutes:10, tags:['TagName=Value'], pollInterval:1000)
Alternatively, you can specify a URL to a template on S3 (you'll need this if you hit the 51200 byte limit on template):
def outputs = cfnUpdate(stack:'my-stack', url:'https://s3.amazonaws.com/my-templates-bucket/template.yaml')
By default the cfnUpdate
step creates a new stack if the specified stack does not exist, this behaviour can be overridden by passing create: 'false'
as parameter :
def outputs = cfnUpdate(stack:'my-stack', url:'https://s3.amazonaws.com/my-templates-bucket/template.yaml', create: 'false')
In above example if my-stack
already exists it would be updated and if it doesnt exist no actions would be performed.
In a case where CloudFormation needs to use a different IAM Role for creating the stack than the one currently in effect, you can pass the complete Role ARN to be used as roleArn
parameter. i.e:
def outputs = cfnUpdate(stack:'my-stack', url:'https://s3.amazonaws.com/my-templates-bucket/template.yaml', roleArn: 'arn:aws:iam::123456789012:role/S3Access')
Note: When creating a stack, either file
or url
are required. When updating it, omitting both parameters will keep the stack's current template.
Remove the given stack from CloudFormation.
To prevent running into rate limiting on the AWS API you can change the default polling interval of 1000 ms using the parameter pollIntervall
. Using the value 0
disables event printing.
cfnDelete(stack:'my-stack', pollInterval:1000)
The step returns the outputs of the stack as map.
def outputs = cfnDescribe(stack:'my-stack')
The step returns the global CloudFormation exports as map.
def globalExports = cfnExports()
Publishes a message to SNS.
snsPublish(topicArn:'arn:aws:sns:us-east-1:123456789012:MyNewTopic', subject:'my subject', message:'this is your message')
Deploys an API Gateway definition to a stage.
deployAPI(api:'myApiId', stage:'Prod')
Additionally you can specify a description and stage variables.
deployAPI(api:'myApiId', stage:'Prod', description:"Build: ${env.BUILD_ID}", variables:['key=value'])
Awaits for a CodeDeploy deployment to complete.
The step runs within the withAWS
block and requires only one parameter:
- deploymentId (the AWS CodeDeploy deployment id: e.g. 'd-3GR0HQLDN')
Simple await:
awaitDeploymentCompletion('d-3GR0HQLDN')
Timed await:
timeout(time: 15, unit: 'MINUTES'){
awaitDeploymentCompletion('d-3GR0HQLDN')
}
Retrieves the list of all AWS accounts of the organization. This step can only be run in the master account.
The step returns an array of Account objects with the following fields:
- id - the account id
- arn - the organizations ARN
- name - the account name
- safeName - the name converted to only contain lower-case, numbers and hyphens
- status - the account status
def accounts = listAWSAccounts()
Create or update a SAML identity provider with the given metadata document.
The step returns the ARN of the created identity provider.
def idp = updateIdP(name: 'nameToCreateOrUpdate', metadata: 'pathToMetadataFile')
- fixes JENKINS-45964: Assuming Role does not work in AWS-China
- Allow opt out for by-default stack creation with
cfnUpdate
- roleArn parameter support for
cfnUpdate
- Fix: Rendering the paths for S3* steps manually (Windows)
- fixes JENKINS-46247: Fix credentials scope in withAWS step and add a credentials dropdown
- add
safeName
tolistAWSAccounts
step
- Add
s3FindFiles
step - add
updateIdP
step - Fix creation of RoleSessionName
- Fix bug when missing DescribeStacks permission
- Make polling interval for CFN events configurable #JENKINS-45348
- Add
awaitDeploymentCompletion
step - Add
s3Delete
step - Add
listAWSAccounts
step
- Replace slash in RoleSessionName coming from Job folders
- improve S3 download logging #JENKINS-44903
- change RoleSessionName to include job name and build number
- add the ability to use a URL in cfnValidate
- add support for create stack timeout
- add the ability to use a URL in cfnUpdate
- add deployAPI step
- add support for externalId for role changes
- allow path to be null or empty in S3 steps
- fix environment for withAWS step
- add support for recursive S3 upload/download
- fix #JENKINS-42415 causing S3 errors on slaves
- add paramsFile support for cfnUpdate
- allow the use of Jenkins credentials for AWS access #JENKINS-41261
- add cfnExports step
- add cfnValidate step
- change how s3Upload works to use the aws client to guess the correct content type for the file.
- add empty checks for mandatory strings
- use latest AWS SDK
- add support for CloudFormation stack tags
- add support for publishing messages to SNS
- fail step on errors during CloudFormation actions
- add proxy support using standard environment variables
- add cfnDescribe step to fetch stack outputs
- fixing invalidation of CloudFront distributions
- add output of stack creation, updates and deletes
- Only fetch AWS environment once
- make long-running steps async
- first release containing multiple pipeline steps