...or another way to put it 'you're going to lose several hours of your life to this stupid error message that you'll never ever get back'.
Puppet is a great tool for automated system builds. But as with anything that uses SSL, it can be an utter pig if you start doing things that stray from the standard install guide.
Our scenario looked fairly simple; a handful of puppet agents finding their master by looking up 'puppet.[domain]' - but with a small twist of puppet being a DNS CNAME to another host. My belief was that the agent would be clever enough to follow the CNAME reference and accept the correctly issued certificate from the alternative name. No. Not the case...
The agent (unless configured otherwise) will only lookup 'puppet' and 'puppet.[domain]'. So no matter how you configure your puppetmaster with certs for different DNS names, unless you've added those DNS names to the agent /etc/puppet/puppet.conf file under the 'server=' setting - it won't work. Ever.
There are articles about setting dns_alternative_names when you generate the puppetmaster certificates which is great - but nothing tells you that won't be any use until you configure the client to accept that new hostname.
The page here http://docs.puppetlabs.com/guides/troubleshooting.html points you in the right direction - but is a bit misleading when it doesn't mention that you have to edit the 'server' property on the AGENT too.
The simplest way to solve this that I could find was to configure your puppetmaster to use the setting in /etc/puppet/puppet.conf of 'certname=puppet'. OK, internally the cert name will be different to the actual hostname but it will please the puppet agents and you won't have to edit all of your agent settings in the long run. You can still have the host and DNS name as whatever you like because puppet doesn't ever change the hostname it's requesting after following DNS.
I hope other people getting caught up on this manage to find this and save at least a few minutes of angry typing / throwing heavy things across the room.