{section: Using HTCondor Annex for the First Time}

We assume you already have an AWS account, as well as a log-in account on a Linux machine with a public IP address and an administrator who's willing to open a port for you.  If so, you can follow the instructions for UsingCondorAnnexForTheFirstTime.

{section: What You'll Need to Know}

To create a HTCondor annex with on-demand instances, you'll need to figure out four things:

1: A name for it.  "MyFirstAnnex" is a fine name for your first annex.
1: Which {link: https://aws.amazon.com/ec2/instance-types/ instance type} you want to use.  Each type of instance has a different number (and type) of CPU cores, amount of RAM, size of local storage, and the like.  If you're not sure, we recommend starting with 'm4.large', which has 2 CPU cores and 8 GiB of RAM.
1: How many instances you want.  For your first annex, when you're checking to make sure things work, you may only want one instance.
1: The duration of the annex, expressed as a whole number of seconds.  Twenty minutes (1200 seconds) should be long enough to make sure things are working, but since AWS charges by the whole hour, you may as well ask for fifty minutes, instead (3000 seconds).

=condor_annex= will arrange for your annex's instances to be terminated after its duration has passed.  Once it's in place, this lease doesn't depend on your machine, but it's only checked every five minutes, so give your deadlines a lot of cushion to make you don't get charged for an extra hour.

{section: Start an Annex}

If you agree with the suggestions above, entering the following will start an annex.

{term}
$ condor_annex -duration 3000 -count 1 -annex-name MyFirstAnnex -odi-instance-type m4.large
MyFirstAnnex[something-something-something]
{endterm}

This command will return after HTCondor has set up the 3000-second (50 minute) lease and requested that Amazon start 1 instance.  The output can be used on AWS to identify annex instances; you won't have to do that unless something goes wrong.

The sharp-eyed among you may have spotted =m4.large= on both the command line and the in the HTCondor configuration; specifying =-odi-instance-type= is in fact optional, and =condor_annex= will use the configured value if you don't specify one on the command-line.

{section: Monitor your Annex}

You can find out if that instance has successfully joined the pool in the following way.

{term}
$ condor_status -annex MyFirstAnnex
slot1@ip-172-31-48-84.ec2.internal  LINUX     X86_64 Unclaimed Idle 0.640 3767
slot2@ip-172-31-48-84.ec2.internal  LINUX     X86_64 Unclaimed Idle 0.640 3767

              Total Owner Claimed Unclaimed Matched Preempting Backfill  Drain
 X86_64/LINUX     2     0       0         2       0          0        0      0
        Total     2     0       0         2       0          0        0      0
{endterm}

This example shows that the annex instance you requested has joined your pool.  (The default annex image configures one static slot for each CPU it finds on start-up.)

{section: Stop an Annex}

The following command shuts HTCondor off on each instance in the annex; if you're using the default annex image, doing so causes each instance to shut itself down.

{term}
$ condor_off -master -annex MyFirstAnnex
Sent "Kill-Daemon" command for "master" to master ip-172-31-48-84.ec2.internal
{endterm}

{section: Advanced Usage}

The information is this section is for advanced users and may not apply (or make sense) to everyone.

{subsection: Configure the Annex}

You can customize the configuration of your annex.  If you pass the full path to a directory (for example, =/home/annex/config.d=) to =condor_annex= using the =-config-dir= option, condor_annex will copy the files in that directory to the HTCondor config directory on each annex instance.  This does _not_ replace the customization that =condor_annex= is already doing to configure security and tell the annex instances which pool to join; those changes will be laid down on top of (a temporary copy of) the directory you specified before being transferred to the instances.