Deploying with Kubernetes

The Kubernetes deployment method deploys Neutree, including the control plane and monitoring components, with a single click using a Helm chart.

Prerequisites

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

• The Kubernetes cluster supports persistent storage, has a CSI plugin installed, and has a default storage class configured with ReadWriteOnce filesystem provisioning.

  When used with AKE, enable the CSI plugin for the AKE workload cluster in Arcfra Operation Center. For details, see the Managing addons and Managing storage classes sections in the Arcfra Kubernetes Engine Administration Guide.

• The Kubernetes cluster supports LoadBalancer-type services and has at least 3 LoadBalancer service addresses allocated.

  When used with AKE, enable the MetalLB plugin for the AKE workload cluster in Arcfra Operation Center and allocate at least 3 LoadBalancer service addresses. For details, see the Managing addons section in the Arcfra Kubernetes Engine Administration Guide.

Preparation

1. Configure kubeconfig. For the configuration method, see Organizing cluster access using kubeconfig files.

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

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

   Note

   Neutree uses JWT (JSON Web Token) for authentication and authorization. The JWT secret is used to ensure the security of JWTs.

3. Upload the Neutree control plane offline image to the image registry of your Kubernetes cluster.

   1. Download version 1.0.1 of the Neutree CLI tool and the control plane offline image according to the server’s CPU architecture.

   2. Grant the CLI tool executable permissions:

      chmod +x neutree-cli-<arch>

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

   3. Use the CLI tool to upload the control plane image to the specified image registry:

      Note

      If your environment has internet access, the system supports pulling container images from Docker Hub. You can skip this step.

      ./neutree-cli-<arch> import controlplane \
        --package <controlplane_package> \
        --mirror-registry <mirror_registry> \
        [--registry-project <registry_project>] \
        --registry-username <registry_username> \
        --registry-password <registry_password>

      Parameter	Description
      <arch>	The server’s CPU architecture: amd64 or aarch64.
      <controlplane_package>	The control plane offline image name, in the format neutree-controlplane-v1.0.1-enterprise-<arch>.tar.gz.
      <mirror_registry>	The image registry address. Enter an OCI-compatible image registry address without the https:// prefix.
      [--registry-project <registry_project>]	Optional. The image registry project name. Ensure the corresponding project has been created in the registry in advance.
      <registry_username>	The username for the image registry, must have image upload permissions.
      <registry_password>	The login password or access key (e.g., token) for the image registry user.

Deployment procedure

1. Download the Helm chart installation file.

2. Create and edit the configuration file:

   helm show values ./neutree-v1.0.1-enterprise.tgz > values.yaml

   Parameter descriptions:

   • Core configuration

     Parameter	Default	Description
     jwtSecret	"mDCvM4zSk0ghmpyKhgqWb0g4igcOP0Lp"	JWT secret string. A default value is provided, but it is recommended to replace it with the JWT secret generated in the preparation steps for production environments.
     adminPassword	None	Custom initial password for Neutree administrator. Optional; recommended to set. If left empty, the system will generate one automatically, which you can retrieve after deployment using kubectl -n neutree logs -l app.kubernetes.io/component=neutree-post-migration-hook-job. The password can only be viewed from the Pod logs during the first deployment.
     imagePullSecrets	[]	Image pull secret list, in the format [{name: "secret-name"}].
     system.grafana.url	""	External Grafana access URL. Leave empty to use the built-in Grafana.
     metrics.remoteWriteUrl	""	Remote metrics storage address. Leave empty to use the built-in Victoria Metrics.

   • Image configuration

     Parameter	Default	Description
     global.image.registry	None	Global remote image registry address. Grafana does not inherit this configuration and must be configured separately.
     global.imageRegistry	None	Grafana remote image registry address.

   • Service configuration

     Parameter	Default	Description
     api.service.type	ClusterIP	API service type. Supports LoadBalancer, NodePort, and ClusterIP.
     api.service.nodePort	""	NodePort port configuration.

   • Storage

     Parameter	Default	Description
     db.persistence.enabled	true	Whether to enable persistent storage for the database.
     db.persistence.size	40Gi	Database storage capacity.
     vmstorage.persistentVolume.size	40Gi	Monitoring 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:

   helm install neutree neutree-v1.0.1-enterprise.tgz -f values.yaml \
     --namespace=neutree \
     --create-namespace

4. Check the Pod status:

   kubectl get pods -n neutree

5. Use the administrator account admin@neutree.local and the initial password to access the Neutree management interface.

   • If api.service.type is NodePort, the access URL is http://<NODE_IP>:<nodePort>.

   • If api.service.type is LoadBalancer, the access URL is http://<LOADBALANCER_IP>:3000.

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

Modifying monitoring component configuration

After deployment, Neutree enables the VictoriaMetrics and Grafana monitoring components by default. You can modify the monitoring component 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 the 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 the built-in Grafana
  image:
    registry: registry.example.com/neutree-ai
  adminUser: admin
  adminPassword: your-secure-password # Must be changed in production environments