This is an Open Service Broker API-compliant custom domain broker for AWS Elastic Load Balancing, designed primarily for Cloud Foundry.
Warning: This is nearly production ready, but still has a long way to go on features.
It's important to note this broker and it's configuration was designed first and foremost for AWS GovCloud, which has some limitations when it comes to global configurations. For example, Route53 is not avaialble in GovCloud as it's a global service, so while the domain broker can be deployed as a Cloud Foundry app in GovCloud, it still needs to cross the boundary into the AWS commercial cloud.
NB: Is the above still the case?
Note: This README focuses on deployment and usage. If you're a developer working on the broker, you probably want to check out the developer documentation as well.
When users request a domain service instance, this broker will provision a Let's Encrypt certificate, an ELB and a CloudFront CDN, and wire them all up together. It does not attempt to manage DNS (as most users already have DNS solutions in place).
This requires a manual step to be performed by the user after the instance is created, as described... here:
We have some constraints that make the Let's Encrypt Challenge process "difficult":
HTTP01
with CloudFront gives us a chicken-and-egg problem, in that CloudFront
will not answer to a custom domain, even for HTTP, without verifying ownership
of that domain via a valid SSL
certificate:
If you want to use an alternate domain name with your CloudFront distribution, you must verify to CloudFront that you have authorized rights to use the alternate domain name. To do this, you must attach a valid certificate to your distribution, and make sure that the certificate comes from a trusted CA that is listed on the Mozilla Included CA Certificate List. CloudFront does not allow you to use a self-signed certificate to verify your authorized rights to use an alternate domain name.
We still need to fully investigate ALPN01
, and its support in CloudFront.
It's not clear if the ALPN01
certificate is a self-signed cert - if so, we'll
likely hit the same CloudFront limitation listed above.
Investigation pointers:
- CloudFront supports HTTP/2
- ALPN is the required SSL implementation for HTTP/2
- Dehydrate bash ACME client can generate ALPN certs.
We do not have access to or control over DNS for the application, so we cannot
automate the DNS01
challenge.
Because of these limitations, we return instructions to the end user as to how
to configure their DNS TXT
record. We then monitor DNS for the record to be
set and propagated globally before continuing with the DNS01
challenge
verification.
The Broker can be configured via the following environment variables:
Variable | Meaning |
---|---|
AWS_ACCESS_KEY_ID |
AWS access key |
AWS_SECRET_ACCESS_KEY |
AWS secret access key |
AWS_DEFAULT_REGION |
AWS region to use |
ACME_ROOT |
todo (mxplusb): this needs to go in acceptance_tests |
ACME_URL |
ACME server url, self-hosted, LE staging, or LE prod works. |
ALB_NAMES |
The resource names of the ELBs/ALBs you want to use for brokering custom domains. format: alb-0,alb-1 |
BROKER_NAME |
The name of the cf app which gets deployed. |
BUCKET |
The S3 bucket which will be used for HTTP01 renewals. |
DATABASE_URL |
The Postgres database URL. |
DELETE_TEST_SERVICE_INSTANCE |
todo (mxplusb): this needs to go in acceptance-tests |
EMAIL |
The registration email used to register new domain names. |
IAM_PATH_PREFIX |
The IAM namespace to use. |
LOG_LEVEL |
todo (mxplusb): make sure this actually does the thing |
PASS |
todo (mxplusb): I think this is the broker password, need to document better |
RESOLVERS |
DNS pre-check resolvers, see more below |
SERVICE_OFFERINGS |
todo (mxplusb): figure out what this means |
URL |
todo (mxplusb): this too |
USER |
todo (mxplusb): I think this is the cf broker username |
Tip: These map directly to the keys in
RuntimeSettings
.
The internal ACME client leverages a custom DNS resolver pre-check. This means
the internal ACME client will try to resolve TXT
records from DNS01 challenges
before informing the upstream ACME server the record is ready to be resolved.
As part of that, if no resolvers are set, no DNS01 records will be able to be created as nothing will resolve (and the broker will likely crash).
The resolvers (can be more than one) must be in the following format per resolver:
{Name}={IP}:{Port}
. For example:
RESOLVERS="level3=4.2.2.2:53,google=8.8.8.8:53,internal=192.168.0.2:53"
As this broker manages ELBs, IAM Certificates, CloudFront and other AWS resources, it requires an IAM policy that allows access to those APIs. We've provided a sample policy, but you're responsible for auditing your own security policies. No warranty, etc, etc.
This broker leverages Concourse for it's deployment
automation, but it's not dependent on it. You can find example and live
concourse configuration files in the ci/
directory.