Install NXLog Platform using Helm

This method deploys NXLog Platform on-premises into your Kubernetes cluster and is intended for users who already have hands-on experience with Kubernetes administration, including managing namespaces, persistent storage, and ingress configurations. The steps below guide you through installing your instance using Helm package manager for Kubernetes.

Prerequisites

Before deploying NXLog Platform, you must have access to a Kubernetes cluster that meets the following conditions:

The cluster is running Kubernetes >= 1.32.
The cluster is sized according to the CPU and RAM requirements.
The cluster is running one of the following ingress controllers:
- Traefik
- Ingress NGINX Controller (community-maintained)
- Istio
The following command-line tools are installed:
- kubectl for running commands against Kubernetes clusters.
  Run kubectl version to check the installed version.
- Helm for deploying and managing Kubernetes applications using charts.
  Run helm version to check the installed version.
- jq for processing and transforming JSON data.
  Run jq --version to check the installed version.

You will also need an NXLog Platform API key:

Log in to your NXLog Platform account, or sign up for NXLog Platform if you don’t have an account yet.
In the left navigation menu, click Product download.
Take note of the API key.

Deploy NXLog Platform

Follow these steps to prepare your environment:

Create a Kubernetes namespace:
```
kubectl create namespace nxp
```

Create a secret to store the NXLog container registry authentication details. Replace <your_api_key> with the API key you obtained earlier.

export NXP_API_KEY="<your_api_key>"
export NXP_CLOUD_URL="platform.nxlog.co"

read NXLOG_ACR ACR_USERNAME ACR_PASSWORD < <(echo $(curl -s -H "Authorization: Bearer ${NXP_API_KEY}" https://${NXP_CLOUD_URL}/registry/tenant | jq -r '.registry[]'))

kubectl create secret docker-registry nxp-acr-secret \
  -n nxp \
  --docker-server=$NXLOG_ACR \
  --docker-username=$ACR_USERNAME \
  --docker-password=$ACR_PASSWORD

Add the NXLog Platform Helm chart repository:

helm repo add nxp https://charts.cloud.nxlog.com/
helm repo update

Download and unpack the NXLog Platform Helm chart to access the YAML files for the different deployment profiles:
```
helm pull nxp/nxp --untar
```
Proceed to install the Helm chart using command-line parameters or a YAML file. If you’re using Red Hat OpenShift, refer to Deploying NXLog Platform on OpenShift for additional configuration instructions.

Using command-line parameters

This method installs the Helm chart by setting configuration parameters on the command line with the --set flag. It is a straightforward way to deploy charts and is more suitable for testing.

Run the following command to install the Helm chart and deploy NXLog Platform in your cluster, specifying your values accordingly:

helm install nxp nxp/nxp \
     --set global.domain=<nxlog.example.com> \(1)
     --set global.organizationName=<example> \(2)
     --set global.organizationId=<your_organization_id> \(3)
     --set global.secrets.apiKey.value=<your_api_key> \(4)
     --set global.cloudDomain=platform.nxlog.co \
     --set portalBackend.secrets.defaultAdminEmail.value=<admin_email> \(5)
     --set portalBackend.secrets.defaultAdminPassword.value=<admin_password> \
     --set vault.pkiCommonNameCA="NXLog Platform Root CA" \(6)
     --set vault.pkiCATTL="87600h" \
     --set vault.pkiAgentTTL="720h" \
     --set vault.pkiAgentMaxTTL="8760h" \
     --values nxp/profiles/ingress-<ingress_controller>.yaml \(7)
     --values nxp/profiles/size-<deployment_size>.yaml \(8)
     --namespace nxp

1	Domain name for accessing your NXLog Platform instance in the format `subdomain.domain.tld`. For example, `nxlog.example.com` if your organization’s domain name is `example.com`.
2	Name of your NXLog Platform organization. You can check the name of your organization on https://platform.nxlog.co/orgs.
3	Your organization ID.
4	The API key you obtained earlier.
5	Credentials for the built-in NXLog Platform administrator account.
6	The root Certificate Authority (CA) and agent certificate settings.
7	The ingress controller profile to apply. The chart provides `ingress-*.yaml` files for the supported ingress controllers.
8	Specify the NXLog Platform deployment size profile. The chart provides `size-*.yaml` files for the available deployment sizes. The command should produce output similar to the following: `NAME: nxp LAST DEPLOYED: Thu Sep 18 18:04:08 2025 NAMESPACE: nxp STATUS: deployed REVISION: 1 TEST SUITE: None`

Verify that the deployment was successful by checking the status of the NXLog Platform pods:
```
kubectl get pods -n nxp
```

Using a YAML file

This method installs the Helm chart by setting configuration parameters in a YAML file. It allows you to track configuration changes by using Git and is preferred for production deployments.

Create a new text file named custom-values.yaml and add the following YAML configuration, updating it with your values accordingly:

# custom-values.yaml
global:
  domain: <nxlog.example.com> (1)
  organizationName: <example> (2)
  organizationId: <your_organization_id> (3)
  cloudDomain: platform.nxlog.co
  secrets:
    apiKey:
      value: <your_api_key> (4)
      secretRef: (5)
        name: <secret_name>
        key: <secret_key>

portalBackend:
  secrets: (6)
    defaultAdminEmail:
      value: <admin_email>
      secretRef:
        name: <secret_name>
        key: <secret_key>
    defaultAdminPassword:
      value: <admin_password>
      secretRef:
        name: <secret_name>
        key: <secret_key>

vault: (7)
  pkiCommonNameCA: "NXLog Platform Root CA"
  pkiCATTL: "87600h"
  pkiAgentTTL: "720h"
  pkiAgentMaxTTL: "8760h"

1	Domain name for accessing your NXLog Platform instance in the format `subdomain.domain.tld`. For example, `nxlog.example.com` if your organization’s domain name is `example.com`.
2	Name of your NXLog Platform organization. You can check the name of your organization on https://platform.nxlog.co/orgs.
3	Your organization ID.
4	The API key you obtained earlier.
5	Optionally, specify an existing Kubernetes secret containing the API key. If both `value` and `secretRef` are specified, `secretRef` takes precedence.
6	Credentials for the built-in NXLog Platform administrator account.
7	The root Certificate Authority (CA) and agent certificate settings.

Run the following command to install the Helm chart and deploy NXLog Platform on your cluster:

helm install nxp nxp/nxp \
    --values custom-values.yaml \
    --values nxp/profiles/ingress-<ingress_controller>.yaml \(1)
    --values nxp/profiles/size-<deployment_size>.yaml \(2)
    --namespace nxp

1	Specify the ingress controller profile that will be applied. The chart provides `ingress-*.yaml` files for the supported ingress controllers.
2	Specify the NXLog Platform deployment size profile. The chart provides `size-*.yaml` files for the available deployment sizes. The command should produce output similar to the following: `NAME: nxp LAST DEPLOYED: Thu Sep 18 18:04:08 2025 NAMESPACE: nxp STATUS: deployed REVISION: 1 TEST SUITE: None`

Verify that the deployment was successful by checking the status of the NXLog Platform pods:
```
kubectl get pods -n nxp
```

Configure ingress for NXLog Agent ports

You must expose the following raw TCP ports to connect NXLog Agent instances to NXLog Platform:

TCP 5514: Default port for connecting to the NXLog Platform agent relay. This port is only necessary if you intend to ship logs to NXLog Platform.
TCP 5515: NXLog Platform Agent Management. This port is required to allow NXLog Agent instances to be managed by NXLog Platform.

Below, we provide example instructions on how to expose the relevant ports using the supported ingress controllers. However, you should expose the ports in a way that complies with your existing security and ingress controller configurations.

Traefik

Create a new text file named values-traefik-tcp.yaml and add the following YAML configuration to expose the TCP ports:

# values-traefik-tcp.yaml
ports:
    tcp-5514:
        port: 5514
        expose:
            default: true
        exposedPort: 5514
        protocol: TCP
    tcp-5515:
        port: 5515
        expose:
            default: true
        exposedPort: 5515
        protocol: TCP

service:
    type: LoadBalancer

Run the following commands to apply the configuration:

# Add Traefik Helm repository
helm repo add traefik https://traefik.github.io/charts
helm repo update

# Install or upgrade Traefik
helm upgrade --install traefik traefik/traefik \
    -n traefik --create-namespace \
    -f values-traefik-tcp.yaml

Create a new text file named nxp-agents-tcp.yaml and add the following YAML configuration to route entrypoints to the corresponding NXLog Platform services:

# nxp-agents-tcp.yaml
apiVersion: traefik.io/v1alpha1
kind: IngressRouteTCP
metadata:
    name: nxp-relay-5514
    namespace: nxp
spec:
    entryPoints:
        - tcp-5514
    routes:
        - match: "HostSNI(`*`)"
        services:
            - name: nxp-external-nxlog
            port: 5514
---
apiVersion: traefik.io/v1alpha1
kind: IngressRouteTCP
metadata:
    name: nxp-agents-5515
    namespace: nxp
spec:
    entryPoints:
        - tcp-5515
    routes:
        - match: "HostSNI(`*`)"
        services:
            - name: nxp-agent-manager-backend-agent
            port: 5515

Run the following command to apply the configuration:
```
kubectl apply -f nxp-agents-tcp.yaml
```

Ingress NGINX Controller

Create a new text file named values-nginx-tcp.yaml and add the following YAML configuration to expose the TCP ports and route them to the corresponding NXLog Platform services:

# values-nginx-tcp.yaml
tcp:
    "5514": "nxp/nxp-external-nxlog:5514"
    "5515": "nxp/nxp-agent-manager-backend-agent:5515"

controller:
    service:
        type: LoadBalancer

Run the following commands to apply the configuration:

# Add Ingress NGINX Helm repository
helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx
helm repo update

# Install or upgrade Ingress NGINX
helm upgrade --install ingress-nginx ingress-nginx/ingress-nginx \
    -n ingress-nginx --create-namespace \
    -f values-nginx-tcp.yaml

Istio

Create a new file named istio-install.yaml and add the following YAML configuration to expose HTTP, HTTPS, and TCP ports 5514/5515 via the Istio operator:

# istio-install.yaml
apiVersion: install.istio.io/v1alpha1
kind: IstioOperator
spec:
  components:
    ingressGateways:
    - name: istio-ingressgateway
      enabled: true
      k8s:
        service:
          ports:
          - name: status-port
            port: 15021
            targetPort: 15021
          - name: http2
            port: 80
            targetPort: 8080
          - name: https
            port: 443
            targetPort: 8443
          - name: tcp-5514
            port: 5514
            targetPort: 5514
            protocol: TCP
          - name: tcp-5515
            port: 5515
            targetPort: 5515
            protocol: TCP

Run the following command to upgrade your Istio installation:
```
istioctl upgrade -f istio-install.yaml
```

Create a new file canamed istio-gateway.yaml and add the following YAML configuration with HTTP to HTTPS redirect, HTTPS termination, and TCP passthrough for agents. Replace instances of nxlog.example.com with the domain name for your NXLog Platform instance.

# istio-gateway.yaml
apiVersion: networking.istio.io/v1
kind: Gateway
metadata:
  name: istio-ingressgateway
  namespace: istio-system
spec:
  selector:
    istio: ingressgateway
  servers:
  - port:
      number: 80
      name: http
      protocol: HTTP
    hosts:
    - "*.nxlog.example.com"
    tls:
      httpsRedirect: true
  - port:
      number: 443
      name: https
      protocol: HTTPS
    hosts:
    - "*.nxlog.example.com"
    tls:
      mode: SIMPLE
      credentialName: wildcard-nxlog-example-com
  - hosts:
    - "relay.nxlog.example.com"
    port:
      name: tcp-5514
      number: 5514
      protocol: TLS
    tls:
      mode: PASSTHROUGH
  - hosts:
    - "agents.nxlog.example.com"
    port:
      name: tcp-5515
      number: 5515
      protocol: TLS
    tls:
      mode: PASSTHROUGH

Run the following command to apply the configuration:
```
kubectl apply -f istio-gateway.yaml
```

Post-installation steps

Once you have installed NXLog Platform, we advise performing the following additional configuration steps immediately to tighten security and initiate important features.

Configure DNS

You need to configure the appropriate DNS records before you can access your NXLog Platform instance. You will likely need to do this on your corporate DNS server.

Create DNS A records for the following domain names and point them all to the IP address of the deployment machine, replacing nxlog.example.com with the actual domain you configured on /etc/nxp.conf while installing NXLog Platform.

platform.nxlog.example.com
agents.nxlog.example.com
relay.nxlog.example.com

For testing purposes, you can add the following entries to the hosts file on your workstation and on any machine running NXLog Agent. Replace 192.168.1.123 with the IP address of your NXLog Platform host machine and nxlog.example.com with the domain you configured on /etc/nxp.conf while installing NXLog Platform:

# Your workstation must resolve the names for the services
# hosting the NXLog Platform UI
192.168.1.123 platform.nxlog.example.com agents.nxlog.example.com

# The machines running agents must resolve the names for the services
# responsible for the NXLog Platform log collection and management
192.168.1.123 relay.nxlog.example.com agents.nxlog.example.com

Set up custom TLS certificates

By default, NXLog Platform uses self-signed certificates to serve the web UI and signing agent certificates. We recommend using your own TLS certificates generated by a local or public Certificate Authority (CA) for production environments.

Certificates are typically configured on the Ingress controller or LoadBalancer service. Your cluster administrator is responsible for managing how users and agents communicate with NXLog Platform.

If you skip this step, the browser will alert you that your connection is not secure when accessing the NXLog Platform web UI.

Log in for the first time

Before you can log in to NXLog Platform, you need to configure DNS.

After the DNS records are in place, open a web browser and navigate to your NXLog Platform URL, replacing nxlog.example.com with your domain:

https://platform.nxlog.example.com

Log in to NXLog Platform using the credentials you defined in /etc/nxp.conf while installing NXLog Platform. If you didn’t change them, use the default credentials for the built-in administrator account:

Username: admin@localhost.local
Password: NXLogPlatform_1

Configure a mail server

NXLog Platform needs to connect to an SMTP server to send emails such as user invites, password reset requests, and system alerts. Without configuring an SMTP server, those features will be unavailable.

Refer to Configure a mail server for step-by-step instructions.

Harden the administrator account

If you haven’t changed the administrator account credentials during installation, we highly recommend changing them after you log in for the first time. We also recommend enabling two-factor authentication (2FA) for the account.

Ensure that you have configured a mail server.
Follow the steps to Update personal information to change the administrator email address. We recommend changing the email address to one that you monitor regularly, as NXLog Platform sends important email notifications to the administrator.

After completing the change, use the new email address for future logins.
Follow the steps to Change your password for the administrator account.
Follow the steps in Activate two-factor authentication to configure 2FA for the administrator account.

Update the NXLog Agent listening port (optional)

If you specified a different agent management port than the default 5515 when setting up the ingress profile, you must follow these additional steps:

Open https://agents.nxlog.example.com/settings/agent-manager, replacing nxlog.example.com with your domain.
Update the port of the default enrollment address and click Save.

This ensures that NXLog Platform sends the correct port when enrolling new agents.
Navigate to Agents > Configurations, and delete all built-in configurations by clicking the Actions menu and choosing Delete.

NXLog Platform automatically recreates the built-in configurations using the updated NXLog Agent listening port.