Dark Deployment – CloudSoda

CloudSoda supports a “dark deployment” configuration, in which the CloudSoda Controller connects to the internet only for installations, upgrades, and ad hoc support requests. This setup imposes additional operational responsibilities on both the customer and CloudSoda, and limits access to certain features. As such, it is only recommended in special circumstances.

In a standard CloudSoda installation, the platform automatically manages DNS and generates valid HTTPS certificates. However, in a dark deployment, the customer is responsible for:

Creating and managing the required DNS records
Installing signed SSL certificates for HTTPS

DNS Creation

Before installing CloudSoda, a server must be provisioned in accordance with the CloudSoda server guidelines. As outlined in the Reference Architecture Guide, the server should be configured with a single IP address, which must be used for all required Fully Qualified Domain Names (FQDNs). CloudSoda requires the following FQDNs:

cloudsoda.myco.com
agent.cloudsoda.myco.com
api.cloudsoda.myco.com
docs.cloudsoda.myco.com
id.cloudsoda.myco.com
intel.cloudsoda.myco.com
llm.cloudsoda.myco.com
orch.cloudsoda.myco.com

In the example above, “cloudsoda” is the hostname, and “myco.com” is the company’s domain name. The primary FQDN (cloudsoda.myco.com) and its associated IP address are required for the installation process. Please have this information ready before requesting the install form, as it will need to be included.

Certificate Creation

To minimize the cost and complexity of managing individual certificates, we recommend including Subject Alternative Names (SANs) in your SSL certificate. This allows you to use a single certificate that secures all required hostnames. The hostnames that should be included are:

Root domain:
cloudsoda.myco.com
SANs (Subject Alternative Names):
api.cloudsoda.myco.com
docs.cloudsoda.myco.com
id.cloudsoda.myco.com
intel.cloudsoda.myco.com
llm.cloudsoda.myco.com
orch.cloudsoda.myco.com

You may notice that no SSL certificate is requested for the "cloudsoda.agent.myco.com" address. This is because the connection uses UDP and has its own built-in TLS encryption, which does not require an SSL certificate.

Alternatively, this can accept a certificate with the root domain and a wildcard subdomain like:

Root domain:
cloudsoda.myco.com
SANs (Subject Alternative Names):
*.cloudsoda.myco.com

Certificate Installation

Once the certificate has been created, combine it with the intermediate certificate (if applicable), then copy both the certificate and the private key to the CloudSoda Controller. Next, SSH into the server and run the following commands:

NAMES="identifier interfacer documenter synaptor tools viewer"

for NAME in $NAMES; do
  kubectl -n soda create secret tls "$NAME-certificate-secret" --cert=cert.crt --key=key.key
done

kubectl -n di create secret tls "api-certificate-secret" --cert=cert.crt --key=key.key

If you receive a message indicating that the secrets already exist, you can safely delete them and then rerun the command above.

NAMES="identifier interfacer documenter synaptor tools viewer"

for NAME in $NAMES; do
  kubectl -n soda delete secret "$NAME-certificate-secret"
done

kubectl -n di delete secret api-certificate-secret

This step is only necessary if you encounter an error while creating your certificate secrets. In that case, simply delete the existing secrets and re-run the commands from the previous step.

Once completed, you should be able to browse to https://cloudsoda.myco.com and see a valid SSL certificate in place.

Updates and Support

In a “dark deployment”, updates must be manually scheduled and temporary remote access must be granted to allow the necessary software to be downloaded and provisioned. Additionally, support can be more challenging in this configuration, as firewall access may be required for troubleshooting.

To streamline support, ensure there is a firewall rule that can be easily enabled and disabled as needed.

Installing and Updating CloudSoda

The CloudSoda Controller installs automatically when a user runs the install script on the provisioned server. An email will be sent to the primary contact, containing a command to retrieve the script and initiate the installation.

Note that some email systems may alter the URL in the email. If this occurs, contact support@cloudsoda.io and our team will assist you in starting the installation process.

Ports and URLs

The following is a detailed list of ports and cloud endpoints.

Ports: TCP 80, 443 for pulling container images. CloudSoda pulls images from the following locations. These need to be accessible for the install and all updates.

us-west1-docker.pkg.dev/services-337921

Ports: TCP 80, 443, 3080 for the control plane. These ports need to be open for install, updates and remote support.

https://cloudsoda.teleport.sh

Port: TCP 50051 for CloudSoda location and price book service.

compass.cloudsoda.io
books.cloudsoda.io

The following endpoints are necessary for the install only. However, we recommend for the install to temporarily allow all HTTPS traffic out to ensure a smooth installation.

https://k3s-ci-builds.s3.amazonaws.com
https://cloudsoda.teleport.sh
https://cannery.cloudsoda.io
https://cloudsodainitscripts-usw2-p-1.s3.amazonaws.com