Deployment Overview of Chainstack on Server¶

Prerequisites and Basic Requirements¶

The deployment of the Chainstack Control Panel requires a Linux server running Ubuntu. The installation process assumes the following system configurations and privileges:

• Operating System: Ubuntu (specific version not restricted, but standard Ubuntu repositories are used).
• Privileges: Root access or sudo privileges are required to install system packages, configure the kernel, and manage services.
• Domain Configuration: A valid domain name is required for the ingress controller to issue SSL certificates via Let's Encrypt. The default zone is hostkey.in.
• Ports: The application listens on port 80 for HTTP traffic, which is automatically redirected to HTTPS. The Kubernetes API listens on port 6443 locally.
• Swap Space: A swap file of 24G is created and enabled at /swapfile to ensure sufficient memory for blockchain node operations.
• Kernel Parameters: Specific sysctl parameters are applied to optimize network and memory performance for blockchain workloads.

FQDN of the Final Panel¶

The fully qualified domain name (FQDN) for accessing the Chainstack Control Panel follows the format defined by the zone and prefix variables.

• Zone: hostkey.in
• Prefix: chainstack
• Format: chainstack<Server ID>.hostkey.in
• Protocol: HTTPS is enforced via the Traefik ingress controller.
• Example: If the server ID is 123, the URL would be https://chainstack123.hostkey.in.

File and Directory Structure¶

The deployment creates specific directories and files to manage the application, configuration, and data storage.

• Installation Directory: /opt/chainstack
• Contains the cpctl installer script.
• Kubernetes Configuration:
• Kubeconfig: /etc/rancher/k3s/k3s.yaml
• User Kubeconfig: /root/.kube/config
• System Configuration:
• Sysctl settings: /etc/sysctl.d/99-chainstack.conf
• Swap file: /swapfile
• Credentials:
• Admin credentials file: /root/chainstack_admin_credentials.txt
• Traefik Configuration:
• Helm chart config for TLS: /var/lib/rancher/k3s/server/manifests/traefik-config.yaml
• Helm Values:
• Stored in /root/.config/cp-suite/ (specifically cp-control-panel-*.yaml).

Application Installation Process¶

The Chainstack Control Panel is installed using the cpctl installer script within the Kubernetes environment provided by k3s.

1. Base Dependencies: Essential tools such as curl, wget, git, jq, ca-certificates, and openssl are installed via apt.
2. Kubernetes Tools:
   • kubectl is installed to /usr/local/bin/kubectl.
   • Helm is installed to /usr/local/bin/helm.
   • yq is installed to /usr/local/bin/yq.
3. k3s Installation: The k3s lightweight Kubernetes distribution is installed with the argument --write-kubeconfig-mode 644.
4. Chainstack Control Plane:
   • The cpctl script is copied to /opt/chainstack/cpctl.
   • The installation command executed is:

     /opt/chainstack/cpctl install -v v1.0.0 -s local-path -y
     

   • This installs the Chainstack version v1.0.0 using the local-path storage class.
5. Kyverno: The Kyverno policy engine is installed via Helm into the kyverno namespace to enforce resource mutation policies.

Access Rights and Security¶

Security measures are implemented at the system and application levels to restrict access and manage resources.

• File Permissions:
• The installation directory /opt/chainstack is set to mode 0755.
• The credentials file /root/chainstack_admin_credentials.txt is set to mode 0600 and owned by root.
• The kubeconfig file /root/.kube/config is set to mode 0600.
• User Access:
• The default administrative username is admin.
• The bootstrap password is generated during installation and stored in the credentials file.
• Firewall: The deployment assumes the server firewall allows incoming traffic on ports 80 and 443.
• Kernel Security:
• vm.swappiness is set to 1 to minimize swapping unless necessary.
• vm.vfs_cache_pressure is set to 50 to optimize inode and dentry cache.

Databases¶

The Chainstack Control Panel utilizes persistent storage for its database and state management.

• Storage Class: local-path
• Namespace: control-panel
• Release Name: cp
• Connection: The database is managed internally by the Helm release and is not exposed as a standalone service for external connection. Data persistence is handled via the local-path provisioner within the Kubernetes cluster.

Docker Containers and Their Deployment¶

The application runs within a k3s Kubernetes cluster rather than as standalone Docker containers. The deployment utilizes the following components:

• Orchestration: k3s (Kubernetes)
• Package Manager: Helm
• Namespace: control-panel
• Key Deployments:
• cp-cp-deployments-api: Handles API requests.
• cp-cp-ui: Handles the user interface.
• Policy Engine: Kyverno is deployed in the kyverno namespace to manage cluster policies.

Proxy Servers¶

Traefik is used as the ingress controller to manage external traffic, SSL termination, and routing.

• Ingress Class: traefik
• SSL/TLS:
• Managed via Let's Encrypt (ACME).
• Email for certificate registration: [email protected].
• Storage for ACME data: /data/acme.json.
• Challenge type: tlschallenge.
• Routing Rules:
• Path /api is routed to the cp-cp-deployments-api service on port 8080.
• Path / is routed to the cp-cp-ui service on port 80.
• Middleware:
• A middleware named chainstack-api-strip is created to strip the /api prefix before forwarding requests to the backend service.
• Configuration:
• Traefik configuration is applied via a HelmChartConfig manifest located at /var/lib/rancher/k3s/server/manifests/traefik-config.yaml.

Permission Settings¶

Specific permissions are applied to critical files and directories to ensure security and proper operation.

Location of Configuration Files and Data¶

Configuration files and data are stored in the following locations:

• Sysctl Configuration: /etc/sysctl.d/99-chainstack.conf
• Traefik TLS Configuration: /var/lib/rancher/k3s/server/manifests/traefik-config.yaml
• Helm Values: /root/.config/cp-suite/cp-control-panel-*.yaml
• Kubernetes Manifests: Managed via k3s server manifests directory.
• Credentials: /root/chainstack_admin_credentials.txt

Available Ports for Connection¶

The following ports are utilized for external and internal communication:

• Port 80: HTTP traffic (redirected to HTTPS).
• Port 443: HTTPS traffic for the Chainstack Control Panel UI and API.
• Port 6443: Kubernetes API server (local access only).
• Port 8080: Internal API service port (exposed via Ingress).
• Port 80: Internal UI service port (exposed via Ingress).

Starting, Stopping, and Updating¶

The Chainstack Control Panel is managed as a Kubernetes deployment. Service management is handled via kubectl and helm commands.

• Check Deployment Status:

  kubectl get deployments -n control-panel
  

• Wait for Deployment Readiness:

  kubectl wait --for=condition=available deployment --all -n control-panel --timeout=600s
  

• Restart UI Deployment: The UI deployment can be restarted by patching the deployment with a restart annotation:

  kubectl patch deployment cp-cp-ui -n control-panel -p '{"spec":{"template":{"metadata":{"annotations":{"kubectl.kubernetes.io/restartedAt":"2023-10-27T12:00:00Z"}}}}}'
  

• Update Version: To update the Chainstack version, the cpctl installer is re-run with the new version flag:

  /opt/chainstack/cpctl install -v <new_version> -s local-path -y
  

• Service Management: The underlying k3s service can be managed using standard systemd commands:

  systemctl status k3s
  systemctl restart k3s