Custom TLS certificate

Learn how to enable and work with custom TLS certificates.


Quick navigation

Jump to:

Prerequisites | Supported TLS certificate types | Configure your custom TLS certificate | Access Orka from your custom domain | Access Orka from any domain | Limitations

You can use your own TLS certificate (with a domain such as to access your Orka environment instead of the custom Orka domain (such as and instead of the default Orka endpoints ( or

Custom TLS certificates provide an additional level of security and compliance. They require access via HTTPS.


Before you begin, you must have your own certificate and private key file that meet the following requirements:

  • Both files are in PEM format.
  • The certificate can be a bundle that contains your server, intermediates, and root certificates concatenated (in the proper order) into one file. The necessary certificates must be enabled as trusted certificates on the clients that connect to the cluster.
  • The private key is not passphrase protected.

Supported TLS certificate types

Orka allows you to use any of the following TLS certificates:

  • Single domain TLS certificate with a domain name such as
  • Multi-domain TLS certificate with domain names such as,, etc...
  • Wildcard TLS certificate with a domain name such as *



The asterisk (*) must be in the leftmost position of the domain name. It is impossible to use a double wildcard certificate for a domain (for example, *.*

Configure your custom TLS certificate

  1. Connect to your cluster via VPN. For more information, see VPN Connection.
  2. Make sure you generate your own custom TLS certificate and private key.
  3. Ensure you have the Orka license key available in your IP Plan.
  4. Send a POST request to http://<orka-api-url>/resources/cert/set with the certPath and keyPath files attached in the request. Replace the <full-path-to-the-certificate> and <full-path-to-the-private-key> placeholders as needed.
curl -X POST 'http://<orka-api-url>/resources/cert/set' \
--header 'Content-Type: multipart/form-data' \
--header 'Authorization: Bearer <token>' \
--header 'orka-licensekey: <license key>' \
--form 'certPath=@<full-path-to-the-certificate>' \
--form 'keyPath=@<full-path-to-the-private-key>'
  1. Add an A/AAAA record in your DNS settings that map your custom domain name to the Orka ingress IP address.


What's the Orka ingress IP address?

For clusters initially deployed with Orka 2.1+, the Orka ingress IP address is the .22 address for the Private-1 network from your IP Plan. For example:

For clusters initially deployed before Orka 2.1, the Orka ingress IP address is the .241 address for the Private-1 network from your IP Plan. For example:

Access Orka from your custom domain

  • For the Orka API, change your API requests to target https://<your-custom-domain>.
  • For the Orka CLI, run orka config and change the URL setting to https://<your-custom-domain>.
  • For the Orka Web UI, open https://<your-custom-domain> in your browser.
  • For CI/CD integrations, switch to https://<your-custom-domain> in the respective plugin configuration.

You need to use https with your custom TLS domain.



You can use your Orka API endpoint ( or and your custom TLS domain ( interchangeably in your workflows.

Access Orka from any domain

  1. Generate a self-signed TLS certificate by running openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 -nodes and following the prompts
  2. Upload the self-signed certificate to the Orka server using the steps here
  3. Ensure the self-signed TLS certificate is trusted according to your configuration.

For example:

  • For the requests to the Orka API, trust the certificate on your local system.
  • For the Orka CLI, run export NODE_EXTRA_CA_CERTS=<path-to-your-self-signed-certificate> and then run orka config
  • For the Orka Web UI, add the certificate to the trusted store of your browser.


  • You cannot use Orka app domain together with a custom TLS certificate.
  • You cannot use more than one custom TLS certificate at the same time.
  • You can use a custom TLS certificate only if your environment is updated to Orka 1.5.0 or later.

Β© 2019-2023 Copyright MacStadium, Inc. – Documentation built with Orka is a registered trademark of MacStadium, Inc.