Skip to content
Neutree Documentation

Kubernetes Deployment

Kubernetes deployment will deploy Neutree including control plane and monitoring components in one step using Helm Chart.

Prerequisites

Section titled “Prerequisites”

To ensure successful deployment of Neutree, please confirm that you have access to the Kubernetes cluster’s image registry, and that your Kubernetes cluster meets the following requirements:

  • Kubernetes cluster supports persistent storage, with a CSI plugin installed and a default StorageClass configured that supports ReadWriteOnce with filesystem volume mode.

  • Kubernetes cluster supports LoadBalancer type services and can allocate at least 3 LoadBalancer service addresses.

Preparation

Section titled “Preparation”

  1. Configure Kubeconfig. For specific configuration methods, please refer to Organizing Cluster Access Using kubeconfig Files.

  2. Run the following command to generate a random JWT secret:

    Terminal window
    openssl rand -base64 32 | tr '+/' '-_' | tr -d '='

  3. Upload the Neutree control plane offline image to the Kubernetes cluster’s image registry.

    1. Download the Neutree CLI installation file and control plane offline image file for the specified version according to your server’s CPU architecture.

    2. Grant executable permissions to the CLI installation file:

      Terminal window
      chmod +x neutree-cli-<arch>

      Replace <arch> with your server’s CPU architecture: amd64 or aarch64.

    3. Upload the control plane image to the specified image registry using the CLI tool:

      Terminal window
      ./neutree-cli-<arch> import controlplane \
        --package <controlplane_package> \
        --mirror-registry <mirror_registry> \
        --registry-username <registry_username> \
        --registry-password <registry_password>
      ParameterDescription
      <arch>Server CPU architecture: amd64 or aarch64.
      <controlplane_package>Control plane offline image filename, format: neutree-controlplane-1.0.0-<arch>.tar.gz.
      <mirror_registry>Image registry address.
      <registry_username>Image registry username with image upload permissions.
      <registry_password>Image registry login password or access key (e.g., token).

Deployment Process

Section titled “Deployment Process”

  1. Download the Helm Chart installation file.

  2. Create and edit the configuration file:

    Terminal window
    helm show values ./neutree-v1.0.0.tgz > values.yaml

    Parameter descriptions:

    • Core Configuration

      ParameterDefaultDescription
      jwtSecret"mDCvM4zSk0ghmpyKhgqWb0g4igcOP0Lp"JWT secret string. A default value is provided, but for production environments, it’s recommended to change it to the JWT secret string generated in the preparation step.
      adminPasswordNoneCustom initial password for the Neutree administrator. Optional but recommended. If left empty, the system will auto-generate one, which can be retrieved after deployment using kubectl -n neutree logs -l app.kubernetes.io/component=neutree-post-migration-hook-job. The password is only viewable via Pod logs during the first deployment.
      imagePullSecrets[]Image pull secrets list, format: [{name: "secret-name"}].
      system.grafana.url""External Grafana access URL. Leave empty to use built-in Grafana.
      metrics.remoteWriteUrl""Remote metrics storage address. Leave empty to use built-in Victoria Metrics.

    • Image Configuration

      ParameterDefaultDescription
      global.image.registryNoneGlobal remote image registry address. Note that Grafana does not inherit this configuration and requires separate configuration.
      global.imageRegistryNoneGrafana remote image registry address.

    • Service Configuration

      ParameterDefaultDescription
      api.service.typeClusterIPAPI service type, supports LoadBalancer, NodePort, ClusterIP.
      api.service.nodePort""NodePort port configuration.

    • Storage

      ParameterDefaultDescription
      db.persistence.enabledtrueWhether to enable database persistent storage.
      db.persistence.size40GiDatabase storage capacity.
      vmstorage.persistentVolume.size40GiMonitoring data storage capacity.

      Configuration Example

      # Core configuration
      jwtSecret: "<jwt_secret>"
      imagePullSecrets: []
      adminPassword: "<admin_password>"
      

      # System configuration
      system:
        grafana:
         url: ""
      

      metrics:
        remoteWriteUrl: ""
      

      # Service configuration
      api:
        service:
          type: LoadBalancer
      

      # Database configuration
      db:
        persistence:
          enabled: true
          size: 40Gi
      

      # Monitoring configuration
      victoria-metrics-cluster:
        vmstorage:
          persistentVolume:
            size: 40Gi
      

      grafana:
        adminUser: admin
        adminPassword: your-secure-password

  3. Install Neutree:

    Terminal window
    helm install neutree neutree-v1.0.0.tgz -f values.yaml \
      --namespace=neutree \
      --create-namespace

  4. Check Pod status:

    Terminal window
    kubectl get pods -n neutree

  5. Access the Neutree management interface using the administrator account admin@neutree.local and the initial password.

    • When api.service.type is NodePort, access via http://<NODE_IP>:<nodePort>.

    • When api.service.type is LoadBalancer, access via http://<LOADBALANCER_IP>:3000.

    • When api.service.type is ClusterIP, run kubectl -n neutree port-forward svc/neutree-api-service 3000:3000 and access via http://127.0.0.1:3000 from local port 3000.

Modify Monitoring Components Configuration

Section titled “Modify Monitoring Components Configuration”

After Neutree deployment, the monitoring components VictoriaMetrics and Grafana will be enabled by default. You can modify the monitoring components configuration by editing the values.yaml file, such as disabling components, setting storage capacity, and changing passwords.

victoria-metrics-cluster:
  enabled: true # Set to false to disable built-in VictoriaMetrics
  global:
    image:
      registry: "registry.example.com/neutree-ai"
  vmstorage:
    persistentVolume:
      size: 40Gi # Set monitoring data storage capacity


grafana:
  enabled: true # Set to false to disable built-in Grafana
  image:
    registry: registry.example.com/neutree-ai
  adminUser: admin
  adminPassword: your-secure-password # Must be changed in production