I love you AWS but your documentation and support suck enormously
I’ve become an Amazon Web Services (AWS) fangirl but holy their docs are half-baked, and their “support” is hilarious.
For the last decade I’ve been developing websites with my team at illuminea, yet I always stayed far away from Amazon Web Services (AWS) because of this:
That list of services appears when you first login to the AWS Console, and is eye-glaze-inducing. The greatest barrier to getting starting with AWS is that it’s hard to even know where to start. Which of the 50 services in the screenshot above are the ones I need? I know that the abundance of AWS services is one of their strengths, but it also creates a confusing barrier to entry.
After founding my startup, Strattic, we received AWS Activate credits (thank you soooo much AWS and Siftech!) and started building out our platform on AWS. I love learning new things, and was happy I couldn’t avoid AWS any longer. It was time to tame the beast.
Luckily, around that time AWS organized one of their AWSome Day workshops in Jerusalem, and that one day provided enough of an overview to help me get started. It clarified how AWS is structured, and the speaker reviewed the primary services in a high level, but useful way. (Very recommended if you can get to one in your area.)
As I delved in to AWS, I became a fan girl. AWS gives you tremendous power, and in brilliant ways. I truly love it.
But one of the most frustrating aspects of AWS is their documentation, because it sucks, and is even missing important information. And their support is hilarious. As in, kind of a joke.
No non-www websites for you, young-ish lady
Cloudfront is AWS’ CDN and it’s awesome. Tons of edge locations, Gzip functionality, http redirection to https, easy integration with AWS free SSL certificates, lightning fast invalidations, IPv6 support, and more.
But the first time I encountered the documentation issue was when we needed to set up a website with the Cloudfront CDN so that the non-www version of the domain would redirect to the www version while using https. You know, basic, critical website functionality so that the site is encrypted, links don’t break, and people can access a website no matter how they enter the URL. I read and reread the documentation about how to add a CNAME so that the Cloudfront distribution is displayed with a custom URL, and it seemed to indicate this was possible, but I soon realized I was going in circles and their docs only referred to domain names that were being completely managed by AWS’ DNS service, Route 53. There was ZERO documentation about how to get that configured with other DNS services, as if that didn’t need to be explained because surely EVERYONE manages their DNS in Route 53.
Turns out that the reason there’s no reference to the option of managing DNS elsewhere and achieving the above is because it’s impossible. You cannot set up websites using Cloudfront (only) to redirect non-www to www if you are not managing your entire DNS with Route 53.
That should not be a requirement for getting your website to function properly. There are many legitimate reasons a company or organization will not be interested in pointing their whole DNS to Cloudfront (or any particular service — domain name owners should have the freedom to manage their nameservers however they prefer).
I was in touch with AWS architects via our account manager about this issue and told them their competitor, Cloudflare, has a solution for this and they should too. But like their documentation, they kept sending me in circles. I decided I don’t need to help them if they won’t make the effort to understand the issue, and gave up. We created our own workaround for Strattic.
This was the first time I encountered how AWS documentation omits information about what it can’t do. Here are a few more examples.
com.amazonaws.services.cloudfront.model.CNA
MEAlreadyExistsException. Duh.
The next time I encountered a glaring lack of information (and user experience) was when I was trying to add a CNAME domain to a Cloudfront distribution.
I kept getting the most insane, weirdly formatted error in the console:
If you can get past the mildly terrifying and confusing “com.amazonaws.services.cloudfront.model.CNA
MEAlreadyExistsException:” you’ll see there’s some semi-useful information in that red blob of text:
“One or more of the CNAMEs you provided are already associated with a different resource.”
But at first my stressed brain couldn’t get past the first two lines.
Eventually I calmed down enough to read the whole thing, did some research (not in AWS docs, since of course there was nothing there), concluded that the CNAME must be in use somewhere else within the AWS kingdom, and then by some miracle I found it in an old AWS account of mine. I deleted it, and the error went away.
What?! Here are the main problems with this error:
- Big red blob errors in a UI console are intimidating, and incongruous, especially if they don’t speak English.
- The CNAME is associated with “a different resource.” You know how AWS has a billion services and a billion clients each with a billion resources? Good luck in finding where that wily CNAME is. Needle in a haystack is an understatement. AWS should tell you where it’s being used, not just that it’s being used somewhere.
- What if some random user had added my CNAME in their account, inadvertently or malicously, to prevent me from using it? Even if they hadn’t activated it by pointing a CNAME record at it, I’d still be locked out of using that CNAME for a domain I OWN. AWS should only count CNAMES as being in use when they actually have CNAME records pointing to them!
S3 buckets can do anything and have no limitations, says AWS docs. ‘Cept they do. Big time.
S3 is cheap, fast, super-stable, supports version control, multi-region and more. Very cool. According to AWS docs, S3 buckets have some “limitations”, and by limitations they mean guidelines. I mean, just check out this brief page on the subject: Bucket Restrictions and Limitations:
- There’s a 100 bucket limit, but you can ask for more — Thank you AWS, you da best.
- Once a bucket name is in use, no one else can use it — Ok, no biggie.
- No buckets in buckets — Fine, we can use directories.
- Better to create or delete buckets in a separate initialization or setup routine that you run less often — Thanks for the tip AWS!
- Follow our naming conventions, which are pretty reasonable — We got yo back AWS.
- There are some challenges with using S3 bucket names that are not DNS-compliant — Of course there are, sillies!
With limitations like that, who needs…non-limitations?
Except they “forgot” to mention this minor, insignificant limitation:
You can only create a maximum of 50 routing rules per bucket.
Meaning, if you need to use 301 redirects in your site (which applies to any site that’s been around a while or takes itself seriously), you can only configure up to 50 of those.
Is this mentioned in the AWS doc about configuring redirects? Anywhere?
Hell to the no.
You only find out once you’ve carefully crafted and deployed a script that defines the redirects, at which point AWS throws the following error:
Oh, did we forget to mention that “the number of routing rules in a website configuration is limited to 50”? Our bad. Tee hee.
In one forum response, an AWS rep argued that a website shouldn’t need more than 50 redirects anyway. I guess they’ve never had to deal with a real live website. Nobody’s perfect.
And then there’s AWS support…Lol
As part of our AWS Activate credits we also have credits for AWS Business Support, which covers AWS Premium Support (Gold), AWS Support (Business), whatever that means.
From my perspective, contacting AWS support is a last resort since, like their documentation, they send you in circles…often by sending you links to their documentation (see above for lack of usefuleness).
AWS is a complicated and complex thingy. You’d think that their paid support would help users navigate the labyrinth of services, and perhaps even provide advice and feedback.
Nope. The support is only helpful when you need limitations lifted, or other technical issues related to the functioning of their own services need to be dealt with. If you need guidance in any way, fuggetaboutit.
Lack of documentation and community makes AWS, which is already hard, harder.
So I thought it might be just me, however whenever I’ve expressed frustration about these issues to other AWS users, they just nodded their heads in agreement.
I come from the world of WordPress, where the ecosystem is huge and has a community culture of sharing. Almost any issue you encounter has a solution — either published in the WordPress Codex, which actually is useful; in blog posts that community members write to share their knowledge; or on forums and Facebook groups where people are happy to help their fellow WPers.
Not so much in the world of AWS. You can’t depend on the AWS docs; users aren’t really a community, but rather a group of people who happen to be using the same tool, so it doesn’t have as much of a culture of sharing knowledge (though many do share and thank goodness for them because their few posts are way more valuable than the thousands of pages of AWS docs); and so far I haven’t found AWS forums and groups (if you know of any please let me know!!).
I get the sense that AWS is by engineers for engineers, in every sense of the word. Which makes sense, and is fine, but they may want to add a dash of humanity and a pinch of Open Source-style community; and also embrace their limitations and share them so we, their users, won’t waste time implementing things that are supposed to work according to their docs, but in reality do not.
And support that is truly support would be nice too.
