xltrail can be installed on a Kubernetes cluster via Helm chart. You'll need the following prerequisites:
- Kubernetes cluster v1.18.14 - v1.20.2
- kubectl, the Kubernetes CLI
- Helm v3, the Kubernetes package manager
You can start with a single node, but it is recommended to use one with at least 4 cores and 4GB RAM, such as
Standard_D4s_v3 on Azure.
The installation instructions go through the following steps:
- Install ingress-nginx
- Install cert-manager (optional)
- Install xltrail
- Advanced Configuration via values.yaml
1. Install ingress-nginx
The ingress is required to make xltrail accessible from outside your cluster. xltrail expects the community-managed ingress-nginx. Install it by running the following:
kubectl create namespace ingress-nginx helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx helm repo update helm install ingress-nginx ingress-nginx/ingress-nginx --namespace ingress-nginx
This will provision a managed Load Balancer and might take a minute or two. Once ready, you can get the external IP of your Load Balancer via:
kubectl get services/ingress-nginx-controller -n ingress-nginx
In your DNS configuration, create an A record (e.g.,
xltrail.mycompany.com) that points to this IP. Depending on your provider, you may also want to configure a static IP that resolves to the Load Balancer's IP and point your A record to this IP instead. For Azure, see: https://docs.microsoft.com/en-us/azure/aks/static-ip.
If you want to expose your ingress to an internal network, you will have to configure your Helm chart accordingly. For example, on Azure, you need to create a file
internal-ingress.yaml with the following content:
# internal-ingress.yaml controller: service: loadBalancerIP: 10.240.0.42 # TODO: Change to your internal IP annotations: service.beta.kubernetes.io/azure-load-balancer-internal: "true" service.beta.kubernetes.io/azure-load-balancer-internal-subnet: "your-subnet"
Then run the following installation command instead:
helm install ingress-nginx ingress-nginx/ingress-nginx --namespace ingress-nginx -f internal-ingress.yaml
For more details, see: https://docs.microsoft.com/en-us/azure/aks/ingress-internal-ip
2. Install cert-manager
This step is optional but highly recommended to secure access to xltrail via TLS certificates, i.e., enable https. See also the cert-manager docs. Install cert-manager by running the following:
kubectl create namespace cert-manager helm repo add jetstack https://charts.jetstack.io helm repo update helm install cert-manager jetstack/cert-manager --set installCRDs=true --namespace cert-manager
After installing cert-manager, you'll need to create a certificate issuer. Create a file called
cert-issuer.yaml with the following content (make sure to fill in your email address).
This example shows how to configure a certificate of type ACME with Let's Encrypt as the certificate authority, but you can use a different configuration according to your needs by following the cert-manager's docs under Configuration.
# cert-issuer.yaml apiVersion: cert-manager.io/v1 kind: ClusterIssuer metadata: name: xltrail-cert-issuer namespace: cert-manager spec: acme: # The ACME server URL server: https://acme-v02.api.letsencrypt.org/directory # Email address used for ACME registration email: YOUR@EMAIL # Name of a secret used to store the ACME account private key privateKeySecretRef: name: xltrail-acme-private-key # Enable the HTTP-01 challenge provider solvers: - http01: ingress: class: nginx
Then, run the following command to create the certificate issuer:
kubectl apply -f cert-issuer.yaml
At this point you haven't issued any certificates yet, they will be issued when you install xltrail with the option
--set ingress.tls.enabled=true, as we'll see below.
3. Install xltrail
Start by creating a namespace for xltrail. We'll be using
xltrail throughout these instructions, but you may want to call it differently, e.g.,
kubectl create namespace xltrail
Since the remaining commands will have to be run in this namespace, the easiest way is to set your current context to this namespace:
kubectl config set-context --current --namespace=xltrail
Confirm that the namespace has been correctly set:
kubectl config view --minify | grep namespace:
Instead of changing the current context, you could also add the
--namespace=xltrailargument to the commands under 3.2 and 3.3.
Run the following commands to create the required secrets.
Docker Registry (details will be provided by email)
kubectl create secret docker-registry xltrail-registry-credentials --docker-server=registry.gitlab.com --docker-username=<USERNAME> --docker-password=<PASSWORD>
License Key (details be provided by email)
kubectl create secret generic xltrail-license-key --from-literal=LICENSE_KEY=<LICENSE_KEY>
kubectl create secret generic xltrail-secret-key --from-literal=SECRET_KEY=$(head -c 512 /dev/urandom | LC_CTYPE=C tr -cd 'a-zA-Z0-9' | head -c 64)
kubectl create secret generic xltrail-postgresql-password --from-literal=POSTGRES_PASSWORD=$(head -c 512 /dev/urandom | LC_CTYPE=C tr -cd 'a-zA-Z0-9' | head -c 64)
In case you're using an externally hosted PostgreSQL instance, provide the password instead of generating a random one.
kubectl create secret generic xltrail-minio-secret-key --from-literal=MINIO_SECRET_KEY=$(head -c 512 /dev/urandom | LC_CTYPE=C tr -cd 'a-zA-Z0-9' | head -c 64)
If you intend to use LDAP for authentication, set the Bind Password here.
kubectl create secret generic xltrail-ldap-bind-password --from-literal=LDAP_BIND_PASSWORD=<PASSWORD>
You should back up the generated secrets so you can move them to a new cluster if you have to.
With nginx-ingress and cert-manager installed and the secrets created, you can now install xltrail with the following commands:
helm repo add xltrail https://xltrail.com/charts helm repo update helm install xltrail xltrail/xltrail --set ingress.host=<HOST> --set ingress.tls.enabled=true
<HOST> to the domain you configured under point 1, e.g.,
xltrail.mycompany.com. If you skipped point 2 (cert-manager), you will need to disable TLS via
Note that the installation will take a couple of minutes. Confirm that all pods show their status as
Running by running the following command:
kubectl get pods
At this point, consider resetting your current context again via:
kubectl config set-context --current --namespace=default
With all pods running, type your domain name (e.g.,
xltrail.mycompany.com) into a web browser and login with both username and password
- Once you are logged in, you can add new projects and/or Git integrations, see here.
- You can add users manually by going to the user icon on the top right, then
Team. If you would rather want to connect xltrail with your LDAP/AD directory, have a look at the LDAP docs.
Change the admin's password in the app via the user icon on the top right, then selecting
5. Advanced Configuration via values.yaml
For a more detailed configuration of your installation, instead of using
--set statements as we did above, you can adjust the configuration via the Helm chart's
values.yaml file. Start by exporting the file like this:
helm show values xltrail/xltrail > values.yaml
After changing the values, you can install the helm chart as follows (if the chart is already installed, use
helm install xltrail xltrail/xltrail -f values.yaml
If you can't access xltrail, try to access xltrail directly via port-forwarding (you'll need to do this from a local Terminal, not a cloud shell):
kubectl port-forward svc/xt-frontend 8080:80 -n xltrail
This should print the following:
Forwarding from 127.0.0.1:8080 -> 80 Forwarding from [::1]:8080 -> 80
Then go to http://127.0.0.1:8080 in your browser and see if the xltrail login screen appears. If it does, you either have a misconfiguration in your ingress-nginx, cert-manager or in the
ingress configuration of your xltrail Helm chart.