1372906 - Document worker manager's expectations of AMIs

Status: RESOLVED FIXED

(Taskcluster :: Services, enhancement)

Description

[Dustin J. Mitchell [:dustin] (he/him)]

In https://github.com/taskcluster/taskcluster-docs/pull/186 a number of comments have related to how the AWS provisioner expects the AMIs it spawns to behave:
 - start a worker on boot
 - call the provisioner secrets API
 - self-terminate
 - safety termination after 96 hours

I think this is a bit too specific for the manual, but would make a great fit in the reference section, probably as a separate document under the AWS provisioner (so a .md file in its docs/ directory).  Then it can be linked to from the manual.

Pete and John were the folks interested..

Comment 1

[Dustin J. Mitchell [:dustin] (he/him)]

Pete, is this something you could add?

Comment 2

[Jonas Finnemann Jensen (:jonasfj)]

I note the docs could be like:
 - sequence chart with:
   1) boot
   2) read user-data
   3) Find workerGroup, workerId from ???
   4) get temp creds from provisioner (with retries)
   5) invalidate secret token by calling provisioner again
   6) fetch secrets from tc-secrets
   7) claim work from queue, following queue <-> worker interaction docs
- a json schema for what keys to expect in user-data
- a section for a few of these topics explaining things like:
    * extract provisionerId / workerType from user-data
    * extract config keys from workerType definition from user-data, I suspect it's the data key
    * how workerType definition becomes a launchSpecification

(heavily inspired by https://docs.taskcluster.net/reference/platform/taskcluster-queue/docs/worker-interaction)

I see these as important docs, written for the perspective of someone writing a worker / AMI.

Comment 3

[Dustin J. Mitchell [:dustin] (he/him)]

These docs are important not just for making it easier for people to write workers.  They also represent a contract which helps us and others figure out what we promise and what we might change without notice.  The naming of SSH keys is an example -- we never intended that to be part of the interface, but in the absence of documentation of the interface, there was no reason for anyone to know that.

So I see this as more than a "document in some free time" bug.

Comment 5

[Chris Cooper [:coop] (he/him)]

John: should this be part of the Worker Manager (as docs or whatever)?

Comment 6

[John Ford [:jhford] CET/CEST Berlin Time]

Yes, this should be a part of the worker manager as docs since this is not something which is programmatically enforceable.

Comment 7

[Dustin J. Mitchell [:dustin] (he/him)]

This is largely done:

• https://docs.taskcluster.net/docs/reference/core/worker-manager/aws#worker-interaction (and similar things for other providers) has cloud-specific bits
• https://docs.taskcluster.net/docs/reference/core/worker-manager/worker-interaction describes interactions with the worker-manager
• https://docs.taskcluster.net/docs/reference/platform/queue/worker-interaction describes interactions with the queue
  and we provide a utility (worker-runner) that does the first two.