Installation (Kubernetes)

xltrail can be installed on a Kubernetes cluster via Helm chart. You'll need the following prerequisites:

  • Kubernetes cluster v1.18.14 - v1.21.3
  • 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:

  1. Install ingress-nginx
  2. Install cert-manager (optional)
  3. Install xltrail
  4. Login
  5. Advanced Configuration via values.yaml
  6. Troubleshooting

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.

Internal LoadBalancer

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

3.1 Namespace

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., xltrail-prod etc.

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=xltrail argument to the commands under 3.2 and 3.3.

3.2 Secrets

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>
    
  • Secret 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)
    
  • Postgres

    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.

  • Minio

    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)
    
  • LDAP (optional)
    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.

For example, if you want to retrieve the password of the Postgres user, you could do:

kubectl get secret xltrail-postgresql-password -ojsonpath='{.data.POSTGRES_PASSWORD}' | base64 --decode ; echo

3.3 xltrail

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

Set <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 --set ingress.tls.enabled=false.

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

4. Login

With all pods running, type your domain name (e.g., xltrail.mycompany.com) into a web browser and login with both username and password admin.

  • 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 Settings > 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 Change Password.

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 upgrade instead install:

helm install xltrail xltrail/xltrail -f values.yaml

6. Troubleshooting

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.

results matching ""

    No results matching ""