Custom TLS certificates
3 minute read
Background
LocalStack sometimes performs on-demand fetching of resources from the public internet. This requires that LocalStack is able to access public URLs. If there is a proxy server in your network that uses a non-standard TLS certificate, LocalStack will not be able to download any files on demand. -You may see errors in the logs relating to TLS such as “unable to get local issuer certificate”.
There are three options when running LocalStack:
They all can be summarised as:
- get your proxy’s custom certificate into the system certificate store, and
- configure
requeststo use the custom certificate, - configure
curlto use the custom certificate, and - configure
node.jsto use the custom certificate.
Creating a custom docker image
If you run LocalStack in a docker container (which includes using the CLI, docker, docker-compose, cockpit or helm), to include a custom TLS root certificate a new docker image should be created.
Create a Dockerfile containing the following commands:
FROM localstack/localstack:latest
+You may see errors in the logs relating to TLS such as “unable to get local issuer certificate”.There are three options when running LocalStack:
They all can be summarised as:
- get your proxy’s custom certificate into the system certificate store, and
- configure
requests to use the custom certificate, - configure
curl to use the custom certificate, and - configure
node.js to use the custom certificate.
Creating a custom docker image
If you run LocalStack in a docker container (which includes using the CLI, docker, docker-compose, or helm), to include a custom TLS root certificate a new docker image should be created.
Create a Dockerfile containing the following commands:
FROM localstack/localstack:latest
# or if using the pro image:
FROM localstack/localstack-pro:latest
@@ -333,10 +333,10 @@
ENV REQUESTS_CA_BUNDLE=/etc/ssl/certs/ca-certificates.crt
ENV NODE_EXTRA_CA_CERTS=/etc/ssl/certs/ca-certificates.crt
and build the image:
$ docker build -t <image name> .
Tip
Certificate files must end in .crt to be included in the system certificate store.
-If your certificate file ends with .pem, you can rename it to end in .crt.Starting LocalStack with the custom image
LocalStack now needs to be configured to use this custom image. The workflow is different depending on how you start localstack.
IMAGE_NAME=<image name> localstack start
docker run <docker arguments> <image name>
services:
+If your certificate file ends with .pem, you can rename it to end in .crt.
Starting LocalStack with the custom image
LocalStack now needs to be configured to use this custom image. The workflow is different depending on how you start localstack.
IMAGE_NAME=<image name> localstack start
docker run <docker arguments> <image name>
services:
localstack:
image: <image name>
# the rest of your configuration
Custom TLS certificates with init hooks
It is recommended to create a boot init hook. Create a directory on your local system that includes
- the certificate you wish to copy, and
- the following shell script:
#!/bin/bash
@@ -352,4 +352,4 @@
localstack start --host
macOS
On macOS the custom certificate should be added to your keychain. See this Apple support article for more information.
Then run LocalStack with the environment variables REQUESTS_CA_BUNDLE, CURL_CA_BUNDLE, and `NODE_EXTRA_CA_CERTS``:
$ NODE_EXTRA_CA_CERTS=/etc/ssl/certs/ca-certificates.crt \
CURL_CA_BUNDLE=/etc/ssl/certs/ca-certificates.crt \
REQUESTS_CA_BUNDLE=/etc/ssl/certs/ca-certificates.crt \
- localstack start --host
Windows
Currently host mode does not work with Windows. If you are using WSL2 you should follow the Linux steps above.