There are 2 options for how you can use the Kilo SSL solution:

Single instance solution

In the video tutorial, you will see how to use the Kilo SSL single instance solution.

Multi-instance solution – ready-to-scale with AWS Network Load Balancer and AWS Global accelerator solution

This video tutorial covers all the steps which should be done for the KiloSSL multi-instance setup.

KiloSSL will provide you with an image* of a server which is a web server and SSL certificate management system. Further on we will call it ACM (Automatic Certificate Management server).
You will integrate the ACM quite easily inside your infrastructure and point all your domains to the ACM. The DNS records for your domains should point to the installed ACM server.
Afterward, all requests to your domains will reach the ACM which will proxy requests to the destination you specified as well as signing the response with the relevant certificate.
All the certificates will be automatically renewed until you will remove the domain.
You will be able to add domains via a simple interface or using API.
* As for now the image is only available as Amazon Machine Image (AMI)

Multi-instance related architecture

Architecture for multi-instance Kilo SSL solution includes usage of AWS Network Load Balancer (NLB) and Global Accelerator. (GA)

With Global Accelerator, you are provided with two global static public IPs that act as a fixed entry point to your application, improving availability and optimizes the path to your application.

Network Load Balancer automatically distributes your incoming traffic across EC2 instances in one or more Availability Zones. It monitors the health of its registered targets and routes traffic only to the healthy targets.

All EC2 instances under the same region’s availability zone will exist under the same target group of NLB. You can set up for example 2 instances in Availability Zone “A”, and 2 instances in availability zone “B”. To allow your domains to be configured in DNS using the A-record (using the IP address), you need to have a single IP address that will point requests to NLB. Initially, NLB itself doesn’t allow to have a single entry point IP address, as each NLB’s target group in each availability zone has its own IP. For single IP purposes, Global Accelerator (GA) is used. GA provides 2 IP addresses (you can use any of them during DNS records configuration)

1. Install KiloSSL ACM
2. Perform Initial configuration
3. Migrate the old domains (if needed)
4. Start using

As for now, the KiloSSL image is available only as an AMI (Amazon Machine Image) however we are working hard to make it available on other popular platforms.

Create Security group

1. Go to EC2 dashboard. On the left panel menu, under Network & Security, click Security Groups. In the security groups page, click Create Security Group
2. Set Security Group Name and description, e.g. KiloSSL
3. In the Inbound rules section add the following rules:
   1. Type: HTTP (protocol is the default here TCP, port 80), Source: Anywhere
   2. Type: SSH (protocol is the default here TCP, port 22), Source: Anywhere
   3. Type: Custom TCP, in the port range set value 3000-3001, Source: Anywhere
   4. Type: HTTPS (protocol is the default here TCP, port 443), Source: Anywhere

4. In the Outbound rules section keep the default (Type: All traffic, Protocol: All, Port range: All, destination 0.0.0.0/0
5. Press Create Security Group

1. Go to the EC2 dashboard and press Launch instance button. The Launch an instance wizard will start.

2. Set the name of the instance.
3. In the Application and OS Images (Amazon Machine Image) section type “kilossl” in the search and press enter.
4. Choose AWS & trusted third-party AMIs and select Kilo SSL Pro – Multi-Instance SSL Certificate Management server.
5. In the Key pair section choose your key for SSH connection to your EC2 instances.
6. In the Network settings select your existing security group created before.
7. Launch instance.

1. Follow steps 1-5 of the 2.2.2. Single-instance Kilo SSL setup steps section.
2. In the Summary section, you will be asked to specify the number of the Instances you want to use.
   Please Notice: During the process, you can select only one subnet in one Availability Zone for all the instances. So if you want to set instances in different availability zones you’ve to go through the installation for each zone.
3. Launch instance.

After setting up the ACM machine you will be asked to perform 2 kinds of configuration:

1. ACM and your services machines security setting
2. ACM initial configuration

Securing access via security group

You probably will need to add an additional configuration to your security group which was created before (Inbound and outbound rules set). 

1. 1. For Inbound rules, make port 3000 available ONLY for machines that will be generating the domains via API
   2. For Inbound rules, make port 3001 available only for machines that require access to the web interface. Web interface might be required in the following cases:
      1. Initial set up
      2. ACM monitoring
      3. Manual domains creation

Example:
Let’s say you want the domains to be created automatically via API from several servers within your network, but you want to grant access to the admin panel only to your admins. And your current web server is hosted outside Amazon. So, the setup we recommend is following:

1. Open ACM’s port 3000 for your network IP
2. Open ACM’s port 3001 only for admins machines or some network only admins have access to.
3. Open port 443 on your service server only for ACM machines.
4. Then when you’ll be able to add the endpoint domains in the following manner: add endpointdomain1.com and point it to https://myservices.com/endpoint1 or https://endpoint1.myservices.com or http://:<your service’s IP>:<some port>

Single-instance Kilo SSL setup steps

After the EC2 instance is deployed and running it must obtain a static IP. If you will not perform this step your ACM machine will be getting a new IP every time it is reset. You will use this IP to point your domains/subdomains to this EC2 instance in the future.

When all the ports are opened as described previously you can browse the ACM’s admin panel at http://<ACM’s IP or domain>:3001 which you can enter with the default credentials:
login: admin password: admin

Update ACM service to the latest version: go to the About page and if any updates available – run Update.

Afterward, you will be able to set the following Settings:

1. Admin credentials – here you will be able to edit the admin panel login and password. Please notice that you will not be able to make any changes until updating the default password. While updating the default login is not mandatory, we strongly recommend changing it.
2. AWS DynamoDB settings – will keep your domains data.
3. LetsEncrypt settings – LetsEncrypt will notify you about different events like the coming domain certificate expiration (in a normal situation you shouldn’t be getting such notifications since KiloSSL will renew the certificate by itself but if you did receive such a notification you should contact our support. This field is mandatory to allow KiloSSL to produce SSL certificates automatically.
4. Default destination – allows to set URL of the page to show in the case when some domain already points to ACM machine, but this domain wasn’t added to the list of domains yet. 
5. API key management – here you will be able to generate an API key to be used to authenticate while using KiloSSL API
6. Nginx Configuration

Default redirection settings – when adding a new domain to the ACM’s web server along with the target location where to redirect the request after validating the certificate KiloSSL will also add few settings to take effect during the redirection.

Nging Server Settings – along with Default Nginx Redirect Settings can be used for more precise and personalized Nginx settings. For example, you can specify a log storage file with the access_log and error_log directives.

You will be able to edit all the configurations in the default template (will take effect only on new domains being created) or specifically for each domain on the My Domains page.

Pay attention that the changes are saved directly to the Nginx config file and may affect the web server functioning so before making any change ensure you’re familiar with Nginx Configuration principles.

7. CloudWatch settings – Along with the logs KiloSSL produces on the machine itself you have an option to duplicate the logs to your CloudWatch to view them there or even to attach a monitoring system afterward. Letsencrypt will be sending you error notifications to the provided email, even though we strongly recommend enabling this option since otherwise, you won’t have any option to get notified about problems that happened before generating or renewing the Certificate other than entering the machine itself and viewing the logs.
   Before saving CloudWatch settings in the Admin panel, you must first create a log group “kilossl-acm” in the AWS CloudWatch region, where logs should be stored.
   Then create an AWS user with permissions to write to Cloudwatch and attach the mandatory permissions to this user. The fastest way to do it:
   1. Go to AWS console, open IAM Services, Press Add new user
   2. Add User Name, choose Programmatic access, Press Next
   3. Choose Attach existing policies directly, search for CloudWatchFullAccess and add it to the user
   Diving deeper, this created user should have at least these 5 permissions:
   1. CreateLogGroup
   2. PutLogEvents
   3. DescribeLogStreams
   4. PutRetentionPolicy
   5. CreateLogStream

Mandatory settings

You must set several settings on this page in order to be able to create and manage domains via UI or API. These settings are:

1. Admin credentials (due to security reasons we block functionality if you didn’t change the default password)
2. AWS DynamoDB settings – will keep your domains data.
3. LetsEncrypt Settings – as they are needed for account creation in LetsEncrypt
4. Default Destination – we force clients to set this setting as we want our Kilo SSL users to be aware of this option and in almost all cases this should have some value

For multi-instance configuration you should do the steps described above for each EC2 instance. Visit each application UI with an address like http://public_instance_ip:3001 with the default credentials admin/admin. And set it up like described in this section above.

Notice: Give the same credentials to Dynamo access. If you want to maintain 2 different environments (test, prod), specify a separate table prefix for each of them. 

Then on the Settings page, you can also configure the time interval for automatic syncing certificates from dynamoDb to your servers. This is a period within which all the instances will be updated with a newly created or updated SSL Certificate. 

By default, the synchronization process is set to run every 30 minutes. Keep in mind that every synchronization causes Nginx restart and creates load on the server. So it is not recommended to set a smaller period. (However Nginx is restarted in a graceful manner, so it won’t cause any downtime for your services)

You can also run the synchronization process manually by clicking the Sync manually button on the settings page. It will automatically start a synchronization process to run on the current instance. This option can be useful when adding a new instance to an existing group of Kilo SSL instances. 

If you would like to update the version of KiloSSL on your EC2 instances – you should update one by one on each instance separately.

This section describes steps only for Multi-instance Kilo SSL setup

Open the EC2 dashboard. On the left navigation pane, under Load Balancing, choose Target Groups. You need to create target groups for ports: 80, 3000, 3001, and 443.

1. Press the Create target group button.
2. Choose the next settings:
   • Target type: Instances.
   • Target group name: any name, ex. KiloSsl80.
   • Protocol: TCP, port: 80.
   • Select the VPC containing your instances.
   • For Health checks, set the TCP protocol.
3. Press the Next button.
4. Select the created instances and press Include as pending below button.
5. Press the Create target group button.
6. Do the same for the 3000, 3001, and 443 ports.

Open the EC2 dashboard. In the navigation pane, under Load Balancing, choose Load Balancers.

1. Press the Create Load Balancer button.
2. You need to choose Network Load Balancer
3. Choose the next settings:
   • Name – any name, ex. KiloSslLoadBalancer
   • For Scheme and IP address type, keep the default values.
   • Select zones where your instances are. You can see it in the Instances Table, column Availability Zone. For each zone, you select the IP assigned by AWS
   • For Listeners and routing choose 80 port, and for Default Actions choose the target group, you created in the previous step for this port (port 80)
   • Press Add listener button and do the same for 3000, 3001, and 443 ports.
4. Review your configuration, and choose to Create a load balancer.

1. In the left navigation pane, under Load Balancing, choose Target Groups.
2. Select the newly created target groups.
3. Choose Targets and verify that your instances are ready. If the status of an instance is initial, it’s probably because the instance is still in the process of being registered. Port 443 will become health status after generating your first domain with certificate.
4. In the navigation pane, under Load Balancing, choose Load Balancers.
5. Select the newly created load balancer.
6. Choose Description and copy the DNS name of the load balancer (for example, my-load-balancer-1234567890abcdef.elb.us-east-2.amazonaws.com). Paste the DNS-name:3001 into the address field of the web browser. If everything is working, the application authorization page will be loaded.

1. Step 1: Basic configuration
2. Step 2: Add listeners
3. Step 3: Add endpoint groups
4. Step 4: Add endpoints

1. Open the Global Accelerator console.
2. Choose Create accelerator.
3. Provide a Accelerator name for your accelerator.
4. For Accelerator type, select Standard.
5. For IP address type, select IPv4.
6. Choose Next.

Create a listener to process inbound connections from your users to Global 

1. Set Ports: 80, 443, 3000-3001.
2. Set Protocol: TCP
3. Left Client affinity: None
4. Choose Next.

1. Add one or more endpoint groups, each of which is associated with a specific AWS Region.
2. Choose Next.

1. Click Add endpoint button.
2. Set Endpoint type: Network Load Balancer
3. Set Endpoint: select created Load Balancer
4. Choose Create accelerator.

• proxy_set_header X-Real-Host $host; – this will add X-Real-Host header which will contain the original host of the request since all the request will be redirected to your services via ACM server the host header will contain ACM’s info, so to know the original host of the request you’ll have to use the data from this header.
• proxy_set_header X-Real-IP $remote_addr; – this will add X-Real-IP header which will contain the original IP of the request
• proxy_set_header Referer $http_referer; – this will proxy initial referer header
• proxy_buffering off; – this will disable buffering of responses from the proxied server (as buffering is enabled by default)
• proxy_ssl_server_name on; – this will Enable passing of the server name through TLS Server Name Indication extension when establishing a connection with the proxied HTTPS server. (as this is disabled by default)
• proxy_ssl_protocols TLSv1.1 TLSv1.2; – this will Enable the specified protocols for requests to a proxied HTTPS server. (proxy_ssl_protocols option uses “TLSv1 TLSv1.1 TLSv1.2” as default value)
• proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; – NGINX provides a $proxy_add_x_forwarded_for variable to automatically append $remote_addr to any incoming X-Forwarded-For headers.
• One extra setting will be added for every domain which is created with enabled HTTPS. This setting will force all incoming to http:// requests to be redirected to https://. This setting line will be: if ($scheme = http){ return 301 https://$host$request_uri; }
• All other settings will be Nginx defaults

When all the initial setup is done you can finally start using the KiloSSL. There are few major actions you’ll be able to perform with KiloSSL ACM:

1. Limitations
2. Add domain
3. Edit Destination
4. Deleting domain
5. Getting domains list

1. Each domain will have its own certificate (currently it is not possible to have multiple domains in certificate’s Subject Alternative Names field)
2. If API will get several simultaneous requests to create/revoke certificate – it will process such requests one by one in a queue. As it takes several seconds to create each certificate in Letsencrypt, you will be able to create approximately about 10 certificates per minute.
3. You can use only 1 API key. If you will create new API key – old API key will stop working immediately. API key is shown only once right after creation. If you will forget API key value – the only option is to create a new one.
4. There is an option to update software directly from the site. But using update you can only install the latest existing version of the program. Currently you can’t install back one of the previous versions. On demand, you can contact support in order to get instruction about how to install one of the previous versions.
5. There is no option to use staging Letsencrypt environment for test purposes. Check Letsencrypt limitations in order not to meet any rate limits. Here are the limitations which are more likely to be reached
   1. Only 50 certificates for specific domain can be created per week
   2. Revoking certificates for the domain does not reset rate limits for that domain

When you add new domain – there are 3 available options for managing SSL:

1. create domain with HTTPS support. Before adding the domain to the ACM you must redirect its DNS settings to the ACM via A or CNAME records and while the domain is not redirected you’ll be receiving a Domain not attached (Code=1300) error from KiloSSL. Together with the domain an SSL certificate will be created for the domain and the domain will start being available via https (http requests will be redirected to https). The certificate will be renewed automatically 29 days before its expiration until you delete the domain from the server.
2. create domain without HTTPS support (your domain will work only with HTTP, certificate won’t be created)
3. create domain and import your own existing certificate (this option available currently only from UI). In order to use your own certificate, you should attach 2 files:
   1. The server certificate, which is a public entity. It is sent to every client that connects to the server
   2. The private key, which is a secure entity
   Under the hood  these 2 files will be integrated into nginx configuration like 

   ssl_certificate www.example.com.cert; ssl_certificate_key www.example.com.cert;

   Certificate for this domain will  be renewed automatically when it will be less than 29 days before expiration of imported certificate.

 You’ve 2 ways to add a domain:

1. Browse to your ACM admin panel http://<ACM’s IP address>:3001
2. Go to My Domains page in the ACM admin panel
3. Press the Add Domain button
4. You’ll be asked to provide following information:
   1. Domain you want to add without http or https prefixes (please notice that you won’t be able to change it after the creation)
   2. If HTTPS should be enabled (turned ON by default). When this option is active, you are able to see another setting allowing import of an existing certificate
   3. URL of your service you want the ACM to redirect the request arriving for this domain. It can be http/https, URL containing domain or IP address. Note: If your service is behind https, ACM will ignore any SSL errors (for example if your service uses obsolete or self-signed certificate)
   4. Also, you’ve an option to change the Nginx redirection settings

Check Add Domain API method specification

After domain is created on the ACM you have a possibility to change it’s targeting URL or/and it’s Nginx redirection settings, both via interface and via API.

If this domain was set previously to work over HTTP only (without a certificate), you will be able to

1. enable HTTPS for this domain automatically. This will create new certificate on the server by issuing new certificate from LetsEncrypt
2. enable HTTPS by importing your own existing SSL certificate

1. Browse to your ACM admin panel http://<ACM’s IP address>:3001
2. Go to My Domains page in the ACM admin panel
3. Press the Edit icon near the Domain you want to change
4. You be able to update following information:
   1. URL of your service you want the ACM to redirect the request arriving for this domain.
   2. Also, you’ve an option to change the Nginx redirection settings

Check Update Domain API method specification

Deleting a domain will also cause removal of its SSL certificate and as well as its periodical renewal. You can delete a domain using interface or an API.

1. Browse to your ACM admin panel http://<ACM’s IP address>:3001
2. Go to My Domains page in the ACM admin panel
3. Press the Delete icon near the Domain you want to change

Check Delete Domain API method specification

You will be able to view a list of all your domains and get the following information for them:

1. Domain name
2. Current certificate creation date
3. Current certificate expiration date

1. Browse to your ACM admin panel http://<ACM’s IP address>:3001
2. Go to My Domains page in the ACM admin panel

Check Get Domains API method specification