{"id":13527162,"url":"https://github.com/jenkinsci/ec2-plugin","last_synced_at":"2025-04-13T08:57:06.737Z","repository":{"id":1234122,"uuid":"1169210","full_name":"jenkinsci/ec2-plugin","owner":"jenkinsci","description":"Jenkins ec2 plugin","archived":false,"fork":false,"pushed_at":"2025-04-02T17:20:17.000Z","size":3959,"stargazers_count":285,"open_issues_count":31,"forks_count":698,"subscribers_count":122,"default_branch":"master","last_synced_at":"2025-04-06T05:09:45.959Z","etag":null,"topics":["agent","aws","cloud","jenkins-plugin","spotinst"],"latest_commit_sha":null,"homepage":"https://plugins.jenkins.io/ec2","language":"Java","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jenkinsci.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2010-12-14T20:35:53.000Z","updated_at":"2025-04-04T04:16:47.000Z","dependencies_parsed_at":"2024-01-13T21:39:52.865Z","dependency_job_id":"7fe2a8a3-50c8-43bb-92e0-b4faf51accf9","html_url":"https://github.com/jenkinsci/ec2-plugin","commit_stats":{"total_commits":1241,"total_committers":260,"mean_commits":4.773076923076923,"dds":0.9016921837228042,"last_synced_commit":"66c828cf4a494b364c84a937fdaa43b41759136f"},"previous_names":[],"tags_count":117,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jenkinsci%2Fec2-plugin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jenkinsci%2Fec2-plugin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jenkinsci%2Fec2-plugin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jenkinsci%2Fec2-plugin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jenkinsci","download_url":"https://codeload.github.com/jenkinsci/ec2-plugin/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248688543,"owners_count":21145764,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent","aws","cloud","jenkins-plugin","spotinst"],"created_at":"2024-08-01T06:01:42.342Z","updated_at":"2025-04-13T08:57:06.710Z","avatar_url":"https://github.com/jenkinsci.png","language":"Java","funding_links":[],"categories":["Java"],"sub_categories":[],"readme":"# ec2-plugin\n[![Jenkins](https://ci.jenkins.io/job/Plugins/job/ec2-plugin/job/master/badge/icon)](https://ci.jenkins.io/job/Plugins/job/ec2-plugin/job/master/)\n[![Jenkins Plugin](https://img.shields.io/jenkins/plugin/v/ec2.svg)](https://plugins.jenkins.io/ec2)\n[![GitHub release](https://img.shields.io/github/release/jenkinsci/ec2-plugin.svg?label=changelog)](https://github.com/jenkinsci/ec2-plugin/releases/latest)\n[![Gitter](https://badges.gitter.im/ec2-plugin/Lobby.svg)](https://gitter.im/ec2-plugin/Lobby?utm_source=badge\u0026utm_medium=badge\u0026utm_campaign=pr-badge\u0026utm_content=badge)\n\n# Table of contents\n   * [Introduction](#introduction)\n   * [Usage](#usage)\n      * [Spot Instances](#spot-instances)\n         * [Enable Spot Request](#enable-spot-request)\n         * [Configure Jenkins for Spot Support](#configure-jenkins-for-spot-support)\n         * [Configure AMI for Spot Support](#configure-ami-for-spot-support)\n      * [IAM setup](#iam-setup)\n   * [Configure plugin via Groovy script](#configure-plugin-via-groovy-script)\n   * [Security](#security)\n      * [Securing the connection to Unix AMIs](#securing-the-connection-to-unix-amis)\n         * [Strategies](#strategies)\n            * [Check New Hard](#check-new-hard)\n            * [Check New Soft](#check-new-soft)\n            * [Accept New](#accept-new)\n            * [Off](#off)\n         * [New AMIs](#new-amis)\n         * [Upgrade - Existing AMIs](#upgrade---existing-amis)\n      * [Securing the connection to Windows AMIs](#securing-the-connection-to-windows-amis)\n         * [AMI Set Up](#ami-set-up)\n   * [Known Issues](#known-issues)\n      * [Authentication Timeout](#authentication-timeout)\n      * [Amazon Linux build/connectivity issues](#amazon-linux-buildconnectivity-issues)\n      * [Downgrade from 1.50.2, 1.49.2, 1.46.3 to a previous version](#downgrade-from-1502-1492-1463-to-a-previous-version)\n   * [Change Log](#change-log)\n\n# Introduction\n\nAllow Jenkins to start agents on\n[EC2](http://aws.amazon.com/ec2/) on demand, and\nkill them as they get unused.  \n\nWith this plugin, if Jenkins notices that your build cluster is\noverloaded, it'll start instances using the EC2 API and automatically\nconnect them as Jenkins agents. When the load goes down, excess EC2\ninstances will be terminated. This set up allows you to maintain a small\nin-house cluster, then spill the spiky build/test loads into EC2 or\nanother EC2 compatible cloud.\n\n# Usage\n\nFirst, go to [EC2](http://aws.amazon.com/ec2/) and sign\nup for the service. Once you've installed the plugin, you navigate to\nthe main \"Manage Jenkins\" \\\u003e \"Configure System\" page, and scroll down\nnear the bottom to the \"Cloud\" section. There, you click the \"Add a new\ncloud\" button, and select the \"Amazon EC2\" option. This will display the\nUI for configuring the EC2 plugin.  Then enter the Access Key and Secret\nAccess Key which act like a username/password (see IAM section). \n\nBecause of the way EC2 works, you also need to have an RSA private key that the\ncloud has the other half for, to permit sshing into the instances that\nare started. Please use the AWS console or any other tool of your choice\nto generate the private key to interactively log in to EC2 instances. \n\nOnce you have generated the needed private key you must either store it as\na Jenkins `SSH Private Key` credential (and select that credential in your cloud\nconfig).\n\nIf you do not want to create a new Jenkins credential you may alterantively store it\nin plain text on disk, indicating its file path via the Jenkins system property\n`hudson.plugins.ec2.EC2Cloud.sshPrivateKeyFilePath`.  If this system property has a non-empty value then\nit will override the ssh credential specified in the cloud configuration page.  This\napproach works well for `k8s` secrets that are mounted in a jenkins container for example.\n\nOnce you have put in your Access Key, Secret Access Key, and configured an ssh private key\nselect a region for the cloud (not shown in screenshot). You may define only one\ncloud for each region, and the regions offered in the UI will show only\nthe regions that you don't already have clouds defined for them.\n\nUse \"Test Connection\" button to verify that Jenkins can successfully\ntalk to EC2. If you are using UEC you need to click on Advanced and fill\nout the endpoint details for your cluster.\n\n![](docs/images/cloud.png)\n\nNext, configure AMIs that you want to launch. For this, you need to find\nthe AMI IDs for the OS of your choice.\n[Packer](https://packer.io/) is a good tool for doing\nthat. Jenkins can work with any Unix AMIs. If using an Ubuntu EC2 or UEC\nAMI you need to fill out the `rootCommandPrefix` and\n`remoteAdmin` fields under `advanced`. Windows is currently somewhat\nsupported.\n\nConfiguring labels allows Jenkins to pick the right AMI to start. For\nexample, if all your existing agents labeled \"solaris\" are fully busy\nand you have more builds that are tied to the \"solaris\" label, Jenkins\nwill start the AMIs that have the \"solaris\" label.\n\nInit script is the shell script to be run on the newly launched EC2\ninstance, before Jenkins starts launching a agent agent. If the AMI\ndoesn't have Java pre-installed, you can do this in the init script.\nThis is also a good place to install additional packages that you need\nfor your builds and tests.  The init script is located at\n**/tmp/init.sh** and is owned and run by the user account specified in\nthe \"Remote User\" field (so use of \"sudo\" may be required for non-root\naccounts).\n\n![](docs/images/ami.png)\n\nConfigure several AMIs if you need different OS images.\n\nWith this setting, your Jenkins will automatically start instances when\nthe load goes up, and the instances will be terminated (or stopped - see\nbelow) automatically if it's idle for more than 30 mins.\n\nBy default, instances are terminated when the idle timeout period\nexpires. You can change this by specifying the Stop/Disconnect on Idle\nTimeout flat in the Advanced properties of the AMI configuration. If\nthis is specified, the instance is stopped when the timeout expires. If\nthe instance is required again, then the plugin will look for a stopped\ninstance that exactly corresponds to the AMI specification and resume it\nif found. Otherwise a new instance is started. Having the instances be\nstopped instead of terminated is useful when you are using EBS volumes\nand want to keep them mounted for the life of the instance and reuse the\ninstance for long periods of time. This can greatly reduce the startup\ntime of the instance since it does not have to build the volume from the\nsnapshot.\n\n## Spot Instances\n\nSpot instances are similar to EC2 instances, except for a few key\ndifferences. They are generally more affordable, but they have the\npossibility of being terminated if someone has bid more on them than you\nhave and can take longer to provision.  To mitigate some of these\nissues, your Jenkins and Agent AMIs will need a bit of configuration to\nconvert the Spot agents to register with Jenkins when they spawn up. Due\nto these changes, it may appear that a Spot agent will have failed (with\na red X), but the message associated with the error will inform you if\nthe Spot instance just has not called back yet or not. For more\ninformation on Spot instances, read the information\nhere: \u003chttp://aws.amazon.com/ec2/spot-instances/\u003e .\n\n### Enable Spot Request\n\nTo enable use of Spot as opposed to EC2 for an instance, the \"Use Spot\nInstance\" check box must be checked.  Also, a bid price must be\nspecified.  If you want to determine what the current price of the\ninstance is without going to the AWS website, pick your region and\ninstance type (as you already should) and click \"Check Current Spot\nPrice\".\n\nTo choose between a Persistent or One Time bid (to keep the bid alive\nuntil cancelled or to stop the bid after it has been fulfilled once),\nchoose from the drop down menu.\n\n### Configure Jenkins for Spot Support\n\nFor Jenkins, the major configuration change will be if you have a\nrestrictive firewall, since these instances need to connect back to\nJenkins.  The first configuration change to Jenkins is to change your\nJenkins URL option in the Configure Jenkins page to be the external URL\nto the server.  One port that needs to be open is the one that you use\nto access Jenkins, the other is the JNLP port, which is generally\nrandomly assigned.  To set the JNLP port to something predictable,\nfollow the Connection Mechanism section on this page. [Jenkins\nCLI](https://wiki.jenkins.io/display/JENKINS/Jenkins+CLI)\n\n### Configure AMI for Spot Support\n\nIn order for your EC2 instance to know that it is to be a Jenkins agent,\nit must be preconfigured with start up commands so that it can register\nitself with Jenkins.  The Jenkins information is passed to the Spot\nagents via EC2 user-data.  This information includes the name that\nJenkins has given the agent, and the configured URL for the Jenkins\ncontroller node.  \n\nSample scripts for assisting in configuring an Ubuntu-based AMI to work\nwith the Jenkins ec2-plugin and Spot agents are included with the\ninstallation of the plugin.   \nConfig Script:\n\n```sh\n(jenkins_server)/plugin/ec2/AMI-Scripts/ubuntu-ami-setup.sh\n```\n\nStartup Script:\n\n```sh\n(jenkins_server)/plugin/ec2/AMI-Scripts/ubuntu-init.py\n```\n\nThe config script is run by the user from the EC2 instance with root\naccess.  It installs Java onto the instance, fetches the startup\nscript and sets it to run when the machine starts up.  It can be\nretrieved from the above URL using a command like wget, or copied over\nusing a tool like `scp`.\n\n```sh\nwget (jenkins_server)/plugin/ec2/AMI-Scripts/ubuntu-ami-setup.sh\n```\n\nOnce the scripts have been downloaded, the script can be run. Running\nthis script will also run the `ubuntu-init.py` script, so there is no\nneed to run it on its own.\n\n```sh\nsudo sh ubuntu-ami-setup.sh jenkins_server{:port}\n```\n\nNote: \"http://\" will be prefixed to the jenkins\\_server parameter\n\nThe config script then fetches the startup script and sets up the AMI to\nregister itself with a Jenkins controller node when it gets started.\n\nAfter setting up the image, you can save the image using Amazon’s EC2\nweb console. To do this, right click on your instance from the console\nand select “Create Image (EBS AMI)”.\n\nIn order to set up additional images using other operating systems, you\ncan configure your own startup script based on the startup script above.\n This script should perform the following actions when the machine is\nstarted up:\n\n```sh\n# Verify that Java is installed\n\n# Install Java if it is not installed\n\n# Read user data for the EC2 instance. It is available from [http://169.254.169.254/latest/user-data]\n\n# Values are passed in with the format of JENKINS_URL=[Jenkins_Url]\u0026SLAVE_NAME=[Agent_Name]\u0026USER_DATA=[other_user_data]\n\n# Parse the values to retrieve the Jenkins_Url and Agent_Name\n# Fetch the agent.jar from the Jenkins controller using wget (or something similar)\n\nwget [Jenkins_Url]jnlpJars/agent.jar -O agent.jar\n# Register the agent to the Jenkins controller node\n\njava -jar agent.jar -jnlpUrl [Jenkins_Url]computer/ [Agent_Name] slave-agent.jnlp\n```\n\n## IAM setup\n\nIt's possible to create a separate account for Jenkins using the Amazon\nIAM feature. Go to the IAM tab in the AWS console and create a user. Then go\nto the user's ***Permissions*** tab and use this policy (change username if\nyour user is not called ***jenkins***):\n\n```json\n{\n    \"Version\": \"2012-10-17\",\n    \"Statement\": [\n        {\n            \"Sid\": \"Stmt1312295543082\",\n            \"Action\": [\n                \"ec2:DescribeSpotInstanceRequests\",\n                \"ec2:CancelSpotInstanceRequests\",\n                \"ec2:GetConsoleOutput\",\n                \"ec2:RequestSpotInstances\",\n                \"ec2:RunInstances\",\n                \"ec2:StartInstances\",\n                \"ec2:StopInstances\",\n                \"ec2:TerminateInstances\",\n                \"ec2:CreateTags\",\n                \"ec2:DeleteTags\",\n                \"ec2:DescribeInstances\",\n                \"ec2:DescribeInstanceTypes\",\n                \"ec2:DescribeKeyPairs\",\n                \"ec2:DescribeRegions\",\n                \"ec2:DescribeImages\",\n                \"ec2:DescribeAvailabilityZones\",\n                \"ec2:DescribeSecurityGroups\",\n                \"ec2:DescribeSubnets\",\n                \"iam:ListInstanceProfilesForRole\",\n                \"iam:PassRole\",\n                \"ec2:GetPasswordData\"\n            ],\n            \"Effect\": \"Allow\",\n            \"Resource\": \"*\"\n        }\n    ]\n}\n```\n\nIf you want to launch agents with an IAM Instance Profile, \"iam:PassRole\"\npermission is required.\n\nIf you want to launch Windows agents and use the generated Administrator\npassword, the \"ec2:GetPasswordData\" permission is also required.\n\n# Configure plugin via Groovy script\n\nEither automatically upon [Jenkins\npost-initialization](https://wiki.jenkins.io/display/JENKINS/Post-initialization+script) or\nthrough [Jenkins script\nconsole](https://wiki.jenkins.io/display/JENKINS/Jenkins+Script+Console),\nexample:\n\n```groovy\nimport software.amazon.awssdk.services.ec2.model.InstanceType\nimport com.cloudbees.jenkins.plugins.awscredentials.AWSCredentialsImpl\nimport com.cloudbees.plugins.credentials.*\nimport com.cloudbees.plugins.credentials.domains.Domain\nimport hudson.model.*\nimport hudson.plugins.ec2.EC2Cloud\nimport hudson.plugins.ec2.AMITypeData\nimport hudson.plugins.ec2.EC2Tag\nimport hudson.plugins.ec2.SlaveTemplate\nimport hudson.plugins.ec2.SpotConfiguration\nimport hudson.plugins.ec2.UnixData\nimport jenkins.model.Jenkins\nimport hudson.plugins.ec2.HostKeyVerificationStrategyEnum\nimport hudson.plugins.ec2.ConnectionStrategy\nimport hudson.plugins.ec2.Tenancy\nimport hudson.plugins.ec2.EbsEncryptRootVolume\n\ndef sshPortToConnectWith = '22'\n\n// store parameters\ndef slaveTemplateUsEast1Parameters = [\n  ami:                           'ami-AAAAAAAA',\n  associatePublicIp:             false,\n  spotConfig:                    null,\n  connectBySSHProcess:           false,\n  connectUsingPublicIp:          false,\n  customDeviceMapping:           '',\n  deleteRootOnTermination:       true,\n  description:                   'Jenkins agent EC2 US East 1',\n  ebsOptimized:                  true,\n  iamInstanceProfile:            '',\n  idleTerminationMinutes:        '5',\n  initScript:                    '',\n  instanceCapStr:                '2',\n  javaPath:                      'java',\n  jvmopts:                       '',\n  labelString:                   'aws.ec2.us.east.jenkins.worker',\n  launchTimeoutStr:              '',\n  numExecutors:                  '1',\n  unixData:                      new UnixData(null, null, null, sshPortToConnectWith, null),\n  remoteFS:                      '',\n  remoteAdmin:                   'ec2-user',\n  tmpDir:                        '',\n  securityGroups:                'sg-11111111',\n  stopOnTerminate:               false,\n  subnetId:                      'subnet-SSSSSSSS',\n  tags:                          new EC2Tag('Name', 'jenkins-worker'),\n  type:                          't2.medium',\n  useDedicatedTenancy:           false,\n  useEphemeralDevices:           false,\n  usePrivateDnsName:             false,\n  userData:                      '',\n  zone:                          '',\n  metadataSupported:             true,\n  metadataEndpointEnabled:       true,\n  metadataTokensRequired:        true, // `true` enforces IMDSv2 only (over IMDSv1), an important AWS security best practice\n  metadataHopsLimit:             1,\n  minimumNumberOfInstances:      0,\n  minimumNumberOfSpareInstances: 0,\n  maxTotalUses:                  -1,\n  monitoring:                    false,\n  t2Unlimited:                   false,\n  connectionStrategy:            ConnectionStrategy.valueOf('PRIVATE_IP'),\n  hostKeyVerificationStrategy:   HostKeyVerificationStrategyEnum.valueOf('CHECK_NEW_HARD'),\n  tenancy:                       Tenancy.valueOf('Default'),\n  ebsEncryptRootVolume:          EbsEncryptRootVolume.valueOf('ENCRYPTED'),\n  nodeProperties:                null\n]\n\ndef EC2CloudParameters = [\n  name:      'MyCompany',\n  credentialsId:  'jenkins-aws-key',\n  instanceCapStr: '2',\n  privateKey:     '''-----BEGIN RSA PRIVATE KEY-----\nMIIEogIBAAKCAQEAkjaolzS/3wlfDfQkaXyuBQ5VaodY9/0tm8BUdcfGmv7MQLUg\nG12MNC5MLcR0Oj4NIOJZEZvH3afPmk5UZ1hZWRWupokSXDM3alNFoWzt0SKDTsig\nnHrqouojRbTqZG8dlmAOHom3mTzj3OFG7PyLdsAEOcrVXwnqgBn7mDriXz+dLkFY\nQctsJHXpm3XBNVaZ/Rmx7vAwFSg3XO0DkjRjR2mXadyh4yQX/bMqr1VEAYBBjGtZ\nri9OXAnoBMduNndeRTQ6i4xA2mBW7zcg4qksHUd+0jKN5t8cVxqOSOcCCztgwaXh\nxEa9/SMIS+FR6NOrUQ+w0MxWsspHogWNWif9IQIDAQABAoIBAGLt9r5wY46OsbEo\nSubRBJHJNAQjVhBdTtm+lacnp/rBggQaSYIalr3LwaGJ9jZeO9XPMQLYC7CvVamL\nbFKMlc/P+t8VicW2pb0cYNWrdXH2zy+kUf/urwnSMFF+6sVP5Y4UqhkBh6d4apjO\nGIZLDjYoD/PmiN6IQBGzAufql7ZntgUohYYkHM/ovskZSR6fSKXn91sirlmisfhE\n/74kGfJF2+S/+HYtpcCgYkSYs/c0Ibzw8wEnNaCK+I0zn4Ppp53ip3hOiI3+0EVY\nqnNisqL5yj8wjj1QFfwkVyWCtr7p0U4A4aDza35rxDKpZW/PcZNRK5pbLQzriqo5\nJ9DOQJ0CgYEA2HGwf+GjRMoJCcONjHKP8NJ3KoSBFj0ujJAxhIOyxJveMMS5agCH\n94yNReZEppV7C/1fpcPb9GL38tfAb6VdGHOlFmq7djgkCKH+F7/PvDJ+u+1G871K\nYtvEFlHT6IPUouEfSj+7/eRxZwNEuKkM2x4dOqPXbvKU63HJkxRFdz8CgYEArO89\nWARI2+o82V3ldPEZAIfri+4HD0nYW7UY4hbExdyuYTKL619Wt1nr91ubCnpR5/1s\nxfesBGYHlqsAuHi4tXCaU9aDyK9j+MnWUkDMvG5RXWzLDmrrfmFlohHc6r7HuVuR\ngtVayj8izcZpXew6Vo3ENRdvfxCzT2V7OPnG058CgYAOb465CMCN7vepWgyPyHhH\nNJJUGKBPbmczYs6aqvn6WPb5w7UmF8D5xrsJZXFAtwmM5CpD8QszgoJNBQzFpX7P\nCa+CDj5QhTAKD1vWE6n0QF3phMrNqNtUOpoabvy2Lky5TFB88EFGjrzthO9JbaT4\n3EpQxeqxcKZ0CZPLJnf3mwKBgFu46IhufVZm/q8rpjBIUEJ/1Ob68LOjLyY0/2Wr\nPeLUEYlsDdphTtUg1I71/12nUxoAyFiX7JzIoO3A9TjijtVtS+17sZoXrKagJxSp\nWe33dSBgO7MB8rWtYwJ7BvlbBwPBFYSXNPhgVE1gFzLBwI930cF3FKQIb5KE+L5X\nfKVxAoGAcvNM9HpgtR3ngP7xWkeOWVkV6NDc2GbuYptbAMM7lY2DzG2Dbq1ru6iJ\nn5CNoNomPrHA05Zx2e+DbmrDbJVowSlX5xJKbc3ttYsBZlqYdZmWllpG1np8snwd\nI2vmggm6Uubt0s433SbMwgXonolPH0N7s8VdzVf0/moMUujYcE0=\n-----END RSA PRIVATE KEY-----''',\n  region: 'us-east-1',\n  useInstanceProfileForCredentials: false\n]\n\ndef AWSCredentialsImplParameters = [\n  id:           'jenkins-aws-key',\n  description:  'Jenkins AWS IAM key',\n  accessKey:    '01234567890123456789',\n  secretKey:    '01345645657987987987987987987987987987'\n]\n\n// https://github.com/jenkinsci/aws-credentials-plugin/blob/aws-credentials-1.23/src/main/java/com/cloudbees/jenkins/plugins/awscredentials/AWSCredentialsImpl.java\nAWSCredentialsImpl aWSCredentialsImpl = new AWSCredentialsImpl(\n  CredentialsScope.GLOBAL,\n  AWSCredentialsImplParameters.id,\n  AWSCredentialsImplParameters.accessKey,\n  AWSCredentialsImplParameters.secretKey,\n  AWSCredentialsImplParameters.description\n)\n\n// https://javadoc.jenkins.io/plugin/ec2/hudson/plugins/ec2/SlaveTemplate.html\nSlaveTemplate slaveTemplateUsEast1 = new SlaveTemplate(\n  slaveTemplateUsEast1Parameters.ami,\n  slaveTemplateUsEast1Parameters.zone,\n  slaveTemplateUsEast1Parameters.spotConfig,\n  slaveTemplateUsEast1Parameters.securityGroups,\n  slaveTemplateUsEast1Parameters.remoteFS,\n  InstanceType.fromValue(slaveTemplateUsEast1Parameters.type),\n  slaveTemplateUsEast1Parameters.ebsOptimized,\n  slaveTemplateUsEast1Parameters.labelString,\n  Node.Mode.NORMAL,\n  slaveTemplateUsEast1Parameters.description,\n  slaveTemplateUsEast1Parameters.initScript,\n  slaveTemplateUsEast1Parameters.tmpDir,\n  slaveTemplateUsEast1Parameters.userData,\n  slaveTemplateUsEast1Parameters.numExecutors,\n  slaveTemplateUsEast1Parameters.remoteAdmin,\n  slaveTemplateUsEast1Parameters.unixData,\n  slaveTemplateUsEast1Parameters.javaPath,\n  slaveTemplateUsEast1Parameters.jvmopts,\n  slaveTemplateUsEast1Parameters.stopOnTerminate,\n  slaveTemplateUsEast1Parameters.subnetId,\n  [slaveTemplateUsEast1Parameters.tags],\n  slaveTemplateUsEast1Parameters.idleTerminationMinutes,\n  slaveTemplateUsEast1Parameters.minimumNumberOfInstances,\n  slaveTemplateUsEast1Parameters.minimumNumberOfSpareInstances,\n  slaveTemplateUsEast1Parameters.instanceCapStr,\n  slaveTemplateUsEast1Parameters.iamInstanceProfile,\n  slaveTemplateUsEast1Parameters.deleteRootOnTermination,\n  slaveTemplateUsEast1Parameters.useEphemeralDevices,\n  slaveTemplateUsEast1Parameters.launchTimeoutStr,\n  slaveTemplateUsEast1Parameters.associatePublicIp,\n  slaveTemplateUsEast1Parameters.customDeviceMapping,\n  slaveTemplateUsEast1Parameters.connectBySSHProcess,\n  slaveTemplateUsEast1Parameters.monitoring,\n  slaveTemplateUsEast1Parameters.t2Unlimited,\n  slaveTemplateUsEast1Parameters.connectionStrategy,\n  slaveTemplateUsEast1Parameters.maxTotalUses,\n  slaveTemplateUsEast1Parameters.nodeProperties,\n  slaveTemplateUsEast1Parameters.hostKeyVerificationStrategy,\n  slaveTemplateUsEast1Parameters.tenancy,\n  slaveTemplateUsEast1Parameters.ebsEncryptRootVolume,\n  slaveTemplateUsEast1Parameters.metadataSupported,\n  slaveTemplateUsEast1Parameters.metadataEndpointEnabled,\n  slaveTemplateUsEast1Parameters.metadataTokensRequired,\n  slaveTemplateUsEast1Parameters.metadataHopsLimit,\n)\n\n// https://javadoc.jenkins.io/plugin/ec2/hudson/plugins/ec2/EC2Cloud.html\nEC2Cloud ec2Cloud = new EC2Cloud(\n  EC2CloudParameters.name,\n  EC2CloudParameters.useInstanceProfileForCredentials,\n  EC2CloudParameters.credentialsId,\n  EC2CloudParameters.region,\n  EC2CloudParameters.privateKey,\n  EC2CloudParameters.instanceCapStr,\n  [slaveTemplateUsEast1],\n  '',\n  ''\n)\n\n// get Jenkins instance\nJenkins jenkins = Jenkins.getInstance()\n\n// get credentials domain\ndef domain = Domain.global()\n\n// get credentials store\ndef store = jenkins.getExtensionList('com.cloudbees.plugins.credentials.SystemCredentialsProvider')[0].getStore()\n\n// add credential to store\nstore.addCredentials(domain, aWSCredentialsImpl)\n\n// add cloud configuration to Jenkins\njenkins.clouds.add(ec2Cloud)\n\n// save current Jenkins state to disk\njenkins.save()\n```\n\n## Programmatically adding/updating CloudTemplates\n\nThe plugin supports programmatic addition and update of `CloudTemplates` in an already existing `Cloud` - \nboth can be accomplished via the Jenkins script console [Jenkins script console](https://wiki.jenkins.io/display/JENKINS/Jenkins+Script+Console).\n\nExample:\n\n```java\n // Assuming on the Jenkins instance, there exists an EC2Cloud with the name \"AwsCloud\"\n\n EC2Cloud cloud = (EC2Cloud) Jenkins.get().clouds.stream().filter(cloud1 -\u003e Objects.equals(cloud.getDisplayName(), \"AwsCloud\")).findFirst().get();\n \n SlaveTemplate template = new SlaveTemplate(/*constructor*/); // View available constructors at https://github.com/jenkinsci/ec2-plugin/blob/master/src/main/java/hudson/plugins/ec2/SlaveTemplate.java\n \n // Adding a template\n cloud.addTemplate(template);\n    \n SlaveTemplate template2 = new SlaveTemplate(/*constructor*/);\n // Updating a template. Note the description of an existing SlaveTemplate needs to passed in order for there to be a successful update, otherwise an Exception is thrown\n cloud.updateTemplate(template2, template.description);\n```\n\n# Security\n## Securing the connection to Unix AMIs\nWhen you set up a template for a *Unix* instance (`Type AMI` field), you can select the strategy used to guarantee the\ninstance you're connecting to is the expected one. You should use a strong strategy to guarantee that a\n_[man-in-the-middle attack](https://en.wikipedia.org/wiki/Man-in-the-middle_attack)_ cannot be performed.\n\nYou can select your strategy under the _Advanced..._ configuration, on the _Host Key Verification Strategy_ field of\nevery configured AMI.\n\nThe plugin provides several strategies because each one has its own requirements. So providing more than one allows\n administrators to use the one best fits to their environment. These strategies are:\n\n### Strategies\n#### Check New Hard\nThis strategy checks the SSH host key provided by the instance with the key printed out in the instance console during\nthe instance initialization. If the key is not found, the plugin **doesn't allow** the connection to the instance to\nguarantee the instance is the right one. If the key is found and it is the same as the one presented by the instance,\nthen it's saved to be used on future connections, so the console is only checked once.\n\nRequirements:\n\n* The AMI used should print the key used. It's a common behaviour, for example the _Amazon Linux 2_ AMI prints it\nout. You can consult the AMI documentation to figure it out.\n* The launch timeout should be long enough to allow the plugin to check the instance console. With this strategy, the\nplugin waits for the console to be available, which can take a few minutes. The _Launch Timeout in seconds_ field should\nhave a number to allow that, for example 600 (10 minutes). By default there is no timeout, so it's safe.\n\nThe expected format on the instance console is `algorithm base64-public-key` at the beginning of a line. For example:\n```\necdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBNFNGfKpPS/UT2jAEa0+9aZneku2a7TVwN+MjGesm65DDGnXPcM9TM9BsiOE+s4Vo6aCT9L/TVrtDFa0hqbnqc8=\nssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIHm0sVqkjSuaPg8e7zfaKXt3b1hE1tBwFsB18NOWv5ow\nssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDNTngsAxOCpZwt+IBqJSQ9MU2qVNYzP4D5i1OHfIRXCrnAuJ54GtFzZEZqqo4e1e/JqBQOX3ZPsaegbkzl2uq5FzfFcFoYYXg5gL7htlZ1I2k6/2iIBv7CHAjbpXMkH8WoF2C3vZFRMWLs20ikQpED+9m11VejE19+kqJwLMopyAtq+/mCgiv4nw5QWh3rrrEcbgzuxYoMD0t9daqBq1V0lzRqL36ALVySy7oDjr3YzCN+wMXe1I36kv3lSeCHXnhc53ubrBIsRakWLBndHhPqyyAOMEjdby/O/EQ2PR7vBpH5MaseaJwvRRDPQ6qt4sV8lk0tEt9qbdb1prFRB4W1\n```\nRecommended for:\n\nThis strategy is the most secure. It's recommended for every instance if you can meet the requirements. We recommend,\nwhenever possible, configuring each AMI with _Stop/Disconnect on Idle Timeout_ to take advantage of the ssh host key\ncache allowing next connections to be done faster.\n\n#### Check New Soft\nThis strategy checks the SSH host key provided by the instance with the key printed out in the instance console during\nthe instance initialization. If the key is not found, the plugin **allows** the connection to the instance in order to\nguarantee the instance is the right one. If the key is found and it is the same as the one presented by the instance,\nthen it's saved to be used on future connections, so the console is only checked once.\n\nRequirements:\n\n* The AMI used may print the key used to guarantee the instance is the right one, but **it's not mandatory**.\n* The launch timeout should be long enough to allow the plugin to check the instance console. With this strategy, the\nplugin waits for the console to be available, which can take a few minutes. The _Launch Timeout in seconds_ field should\nhave a number to allow that. For example 600 (10 minutes). By default there is no timeout, so it's safe. If the timeout\nexpires, the connection is not done.\n\nThe expected format on the instance console is `algorithm base64-public-key` at the beginning of a line. For example:\n```\necdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBNFNGfKpPS/UT2jAEa0+9aZneku2a7TVwN+MjGesm65DDGnXPcM9TM9BsiOE+s4Vo6aCT9L/TVrtDFa0hqbnqc8=\nssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIHm0sVqkjSuaPg8e7zfaKXt3b1hE1tBwFsB18NOWv5ow\nssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDNTngsAxOCpZwt+IBqJSQ9MU2qVNYzP4D5i1OHfIRXCrnAuJ54GtFzZEZqqo4e1e/JqBQOX3ZPsaegbkzl2uq5FzfFcFoYYXg5gL7htlZ1I2k6/2iIBv7CHAjbpXMkH8WoF2C3vZFRMWLs20ikQpED+9m11VejE19+kqJwLMopyAtq+/mCgiv4nw5QWh3rrrEcbgzuxYoMD0t9daqBq1V0lzRqL36ALVySy7oDjr3YzCN+wMXe1I36kv3lSeCHXnhc53ubrBIsRakWLBndHhPqyyAOMEjdby/O/EQ2PR7vBpH5MaseaJwvRRDPQ6qt4sV8lk0tEt9qbdb1prFRB4W1\n```\nRecommended for:\n\nThis strategy is the default one for AMIs created with a former version of the plugin. It doesn't break any connection\nbecause the plugin connects to the instance even when the key is not found on the console. The only point to take into\n account is you need to have the right timeout to allow the plugin to get the instance console. This strategy is recommended\nwhen upgrading from a previous version of the plugin. _Check New Hard_ is the safest strategy, so you should\nconsider migrating to it. We recommend, whenever possible, configuring each AMI with _Stop/Disconnect on Idle Timeout_\n to take advantage of the ssh host key cache allowing next connections to be done faster.\n\n#### Accept New\nThis strategy doesn't check any key on the console. It accepts the key provided by the instance on the first\nconnection. Then, the key is saved to be used on future connections to detect a Man-in-the-Middle attack (the host\nkey has changed).\n\nRequirements:\n* N/A\n\nRecommended for:\n\nThis strategy is recommended when your AMIs don't print out the host keys on the console. The _Check New Soft_ cannot be\n used, but at least, you can catch a man-in-the-middle attack on further connections to the same instance. If the attack\n was already perpetrated you cannot detect that. Again, the _Check New Hard_ is the safest strategy.\n\n#### Off\nThis strategy neither checks any key on the console, nor checks future connections to the same instance with a saved\nkey. It accepts blindly the key provided by the instance on the first and further connections.\n\nRequirements:\n* N/A\n\nRecommended for:\n\nThis strategy is not recommended because of its lack of security. It is the strategy used for prior versions of the plugin.\n\n### New AMIs\nThe default strategy for every new instance is the _Check New Hard_ one. You can select a strategy per AMI. It's under\nthe _Advanced..._ configuration, on the _Host Key Verification Strategy_ field.\n\n### Upgrade - Existing AMIs\nYou may upgrade from a Jenkins installation with a former plugin version without this security mechanism. The default\n strategy for every existing instance is the _Check New Soft_ strategy. This guarantees your jobs are not going to stop\n working and improves the situation. We recommend, if possible, upgrading to the _Check New Hard_ strategy to be safer\n against a _Man in the Middle attack_.\n\n## Securing the connection to Windows AMIs\nWhen you configure a template for a *Windows* instance (`Type AMI` field), you can use HTTPS and disallow\nself-signed certificates. This guarantees the instance you're connecting to is the expected one and a\n[man-in-the-middle attack](https://en.wikipedia.org/wiki/Man-in-the-middle_attack) cannot be performed.\n\n### AMI Set Up\nBefore securely connecting to the instance, you need to 1) configure the AMI, 2)install the\ncertificate, 3) configure WinRM properly and 4) set the firewall rules to allow the connection. You can find some\nguidance at the `AMI Type` field help, under the template configuration on your Jenkins instance.\n\nTips:\n* When the `Allow Self Signed Certificate` field is checked, the plugin allows self-signed certificates. It means that\nthe plugin neither checks the CA which issued the certificate, nor verifies the host it is connecting to is present on\nthe certificate. If the field is not checked, this kind of certificates are not allowed and both verifications are performed.\n* The EC2 plugin connects to the instance using either an IP address. It does not use the DNS name. You must configure WinRM with a certificate which includes\nthe **IP** of the instance. Something like:\n```\n#3: ObjectId: 2.5.29.17 Criticality=false\nSubjectAlternativeName [\n  DNSName: myhostname.com\n  IPAddress: 111.222.333.444  \u003c--------------\n]\n```\n# Known Issues\n\n## Authentication Timeout\n\nIf you have issues with authentication timing out as a node is starting\n(see the stack traces in\n[JENKINS-30284](https://issues.jenkins-ci.org/browse/JENKINS-30284)) you\ncan use these System Properties to adjust the number of tries and\ntimeout values:\n\n    jenkins.ec2.bootstrapAuthSleepMs (default 30000)\n    jenkins.ec2.bootstrapAuthTries (default 30)\n\n## Amazon Linux build/connectivity issues\n\nIf you are using a Amazon Linux AMI and encounter exceptions like\n***java.io.FileNotFoundException:\n/usr/lib/jvm/java-1.8.0-openjdk-1.8.0.201.b09-0.amzn2.x86\\_64/jre/lib/currency.data\n(No such file or directory)*** or ***Remote call on EC2\n\\[...\\] failed*** then chances are that the Amazon Linux is doing some\nsecurity upgrades in the background and causes the agent to be in an\ninvalid state.\n\nAnother symptom of the same problem if you run Docker on your agents can be\neither docker containers randomly exiting with ExitCode 137 or getting error\nmessages with \"EOF\" part way through trying to pull or run images - this can occur\nif there is a security patch for Docker itself because applying this update stops\nDocker. These upgrades are asynchronous on Amazon Linux 2 (whereas on the older\nAmazon Linux the docs stated that the SSH service was not started until they complete)\nso your Jenkins job may have already started using Docker, causing this issue.\n\nFrom the\n[documentation](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/amazon-linux-ami-basics.html#security-updates)\nof the Amazon Linux it's stated:\n\n\u003e Amazon Linux is configured to download and install security updates at\n\u003e launch time.\\[...\\] The default setting for repo\\_upgrade is security.\n\u003e That is, if you don't specify a different value in your user data, by\n\u003e default, Amazon Linux performs the security upgrades at launch for any\n\u003e packages installed at that time\n\nYou can check by looking for `repo_upgrade:` in \"cloud-init\" settings `/etc/cloud/cloud.cfg`.\n\nThis issue can be solved in different ways:\n\n1.  Rebuild your AMI so the latest security fixes are baked in =\\\u003e this will mean\n    however that the issue could eventually come back if further patches are published.\n2.  Update the Jenkins config for launching your AMI, so it disables automatic installation of security fixes\n    (see amazon [documentation](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/amazon-linux-ami-basics.html#security-updates))\n    by adding the following in 'User Data' under 'Advanced' for the AMI in Jenkins Clouds config:\n        \n        #cloud-config\n        repo_upgrade: none\n\n3.  If you disable repo_upgrade per the previous point, you can optionally still ensure patches are\n    applied by adding your own yum command in the 'Init script' for the AMI in Jenkins Clouds config,\n    the advantage being that Jenkins will not start using the agent until this init script has finished\n\n    ![](docs/images/init-scripts.png)\n\n## Downgrade from 1.50.2, 1.49.2, 1.46.3 to a previous version\nIf you updated to 1.50.2, or 1.49.2 or 1.46.3 and you need to downgrade back to the previous version, be sure to **remove** the\nfile `JENKINS_HOME/ec2.xml` before doing that. This file is created if you click on the button *Dismiss these messages* of\nthe monitor that warns you when there are some template with a weak  strategy. If you don't do that, Jenkins will start and\nwill overwrite its config.xml file **losing your cloud configuration**.\n\nAt this moment, it seems related with a race-condition between the plugin and the `OldDataMonitor` class of Jenkins Core.\nSee https://issues.jenkins-ci.org/browse/JENKINS-62231\n\n# Change Log\n\nNewer changelogs are posted [here](https://github.com/jenkinsci/ec2-plugin/releases),\n1.45 and older releases can be found [here](https://github.com/jenkinsci/ec2-plugin/blob/master/CHANGELOG.md)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjenkinsci%2Fec2-plugin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjenkinsci%2Fec2-plugin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjenkinsci%2Fec2-plugin/lists"}