External Custom Domains
To work with your own customer domain (e.g., company.com), you need to upload a custom TLS certificate to your cluster.
Quick navigation
Jump to:
1. Obtain a certificate | 2. Upload the certificate | 3. Map the domain to your cluster Ingress | 4. Trust the certificate locally | 5. Configure your tools
Instead of working with the default Orka endpoints (10.221.188.20
or 10.221.188.100
) or your built-in Orka domain (company.orka.app
), you can access your cluster from an external custom domain (for example: company.com
).
Custom domains provide an additional level of security and compliance. To configure an external custom domain for your cluster, you need a TLS certificate. With a valid TLS certificate in place, you need to access your cluster via HTTPS.
Overview
To configure an external custom domain for your Orka cluster, you need to complete the following tasks.
- Obtain a TLS certificate and a private key for the domain.
- Upload the certificate to the cluster.
- Map the custom domain and the Ingress of your cluster.
- Trust the certificate on your local machine.
- Configure your tools.
Limitations
- You can have only one custom TLS certificate uploaded to your cluster at a time. Subsequent uploads replace the current custom TLS certificate.
- Due to Node.js limitations, the Orka CLI can work only with valid TLS certificates issued by the certificate authorities recognized by Node.js.
1. Obtain a certificate
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 private key is not passphrase protected.
- The certificate might be any of the following:
- A single domain certificate (e.g.
company.com
). - Multi-domain certificate (e.g.
app1.company.com
,app2.company.com
, and so on). - Wildcard TLS certificate (e.g.
*.company.com
)
If containing an asterisk, it must be a single asterisk and must be in the leftmost position of the domain name. For example: You cannot use a*.*.company.com
certificate to work with Orka. - A certificate chain (bundle) that contains your server, intermediates, and root certificates concatenated (in the proper order) into one file.
- A single domain certificate (e.g.
- The certificate must be a registered domain certificate issued by a certificate authority OR a self-signed certificate for any domain (for local use only).
2. Upload the certificate
Next, you need to upload the custom TLS certificate and private key to your cluster.
- Connect to your cluster via VPN.
- Send the following POST request to
/api/v1/upload/cert
.
curl --request POST \
--url http://<orka-api-url>/api/v1/upload/cert \
--header 'accept: application/json' \
--header 'content-type: multipart/form-data' \
--form keyPath'keyPath=@<full-path-to-the-private-key>' \
--form certPath='certPath=@<full-path-to-the-certificate>'
Replace <orka-api-ip>
with 10.221.188.20
or 10.221.188.100
.
Replace <full-path-to-the-certificate>
and <full-path-to-the-private-key>
with the full paths to the certificate and the private key on your local machine.
3. Map the domain to your cluster Ingress
Next, map your external custom domain and your cluster. You need to map the domain and the IP of the cluster Ingress.
What's your Ingress IP?
If you reach your Orka endpoint at
*.*.*.20
, the Ingress IP is*.*.*.22
.
For example:10.221.188.22
.If you reach your Orka endpoint at
*.*.*.100
, the Ingress IP is*.*.*.241
.
For example:10.221.188.241
.
3.1 Create a global mapping
If you are working with a registered domain and a TLS certificate obtained from a certificate authority, you can configure a global mapping. You need to add A/AAAA
record in the DNS settings of the domain. This A/AAAA
record must map the external custom domain name to the Orka Ingress IP.
3.2 Create a local mapping
If you want to work with an external custom domain locally and you are using a self-signed TLS certificate, you can map the domain to the Ingress IP in your hosts
file.
macOS and Linux
- In the Terminal, run the following command:
sudo nano /etc/hosts
- When prompted, provide your password.
- At the bottom of the file, on a new line, add the Ingress IP and the custom Orka domain, separated by a space.
<INGRESS-IP> <CUSTOM-DOMAIN>
For example:
10.221.188.22 company.com
- Press
Ctrl+0
and then pressEnter
to save your changes. - Press
Ctrl+X
to exitnano
. - (Optional, macOS) If you cannot reach your custom Orka domain, try flushing the DNS cache.
dscacheutil -flushcache
Windows
- Press the
Windows
key and type Notepad in the search text box. - Right-click the Notepad icon and select Run as administrator.
- In Notepad, select File > Open.
- In the File name text box, type
C:\Windows\System32\drivers\etc\hosts
. - At the bottom of the file, on a new line, add the Ingress IP and the custom Orka domain, separated by a space.
<INGRESS-IP> <CUSTOM-DOMAIN>
For example:
10.221.188.22 company.com
- Save your changes and close the file.
4. Trust the certificate locally
This step is required for self-signed certificates. If you are using a TLS certificate for a registered domain, issued by a recognized certificate authority, you can skip this step.
If you are using a self-signed certificate, you need to add your custom TLS certificate and trust it on all systems that will be accessing your Orka cluster. For some browsers, you might need to add the certificate (if self-signed) to the trusted store of the browser as well.
macOS
- Open Keychain Access.
- Drag and drop the certificate to the login keychain.
- Double-click the newly added certificate.
- Expand the Trust section and for the When using this certificate setting, select Always Trust.
- Close the certificate info window and when prompted, provide your password.
Linux
Run the following commands:
sudo mkdir /usr/local/share/ca-certificates/extra
sudo cp mycertificate.pem /usr/local/share/ca-certificates/extra/mycertificate.crt
sudo update-ca-certificates
Windows
- Rename the certificate and change its extension to
.crt
. - Double-click the file and confirm that you want to open it.
- On the General tab, click Install Certificate.
- For Store Location, select Local Machine and click Next.
- When prompted, confirm that you want
Windows host process
to make changes to your device. - Select Place all certificates in the following store, click Browse and from the list, select Trusted Root Certification Authorities and click OK.
- Click Next, review the settings, and click Finish.
5. Configure your tools
Finally, you need to target your external custom domain with your Orka tools. Note that you need to use https
with your custom TLS domain.
- For the Orka API, change your API requests to target
https://<custom-domain>
. - For the Orka CLI, run
orka config
and sethttps://<custom-domain>
for URL. Note that you can use only valid TLS certificates issued by a limited number of certificate authorities. - For the Orka Web UI, open
https://<custom-domain>
in your browser. - For CI/CD integrations, switch to
https://<custom-domain>
in the respective plugin configuration.
TIP
You can use your Orka API endpoint (
http://10.221.188.20
orhttp://10.221.188.100
) and your custom domain (https://company.com
) interchangeably in your workflows.
See also
Updated 10 months ago