How to Enable or Disable Features in CubeSandbox via Config: A Complete Guide

You can enable or disable features in CubeSandbox by modifying boolean enable_* fields in YAML configuration files such as CubeMaster/conf.yaml and Cubelet/dynamicconf/conf.yaml, then restarting the respective service to apply changes.

CubeSandbox, the open-source sandbox runtime maintained by Tencent Cloud, uses a declarative configuration system to control feature availability across its distributed architecture. Rather than recompiling binaries, you manage capabilities—ranging from network exposure to authentication—through structured YAML files that map directly to Go structs in the source code. This approach allows precise runtime control over cluster behaviors and node-specific functionalities.

Configuration File Locations

CubeSandbox separates feature management between the control plane (CubeMaster) and data plane (Cubelet). Each component reads from distinct YAML files that follow consistent naming conventions.

CubeMaster Configuration

The master control plane reads settings from CubeMaster/conf.yaml. This file governs cluster-wide features including API authentication, exposed port management, and scheduler filters. The configuration maps to the Config struct defined in CubeMaster/pkg/base/config/config.go, where fields like EnableExposedPort correspond to YAML keys such as enable_exposed_port.

Cubelet Dynamic Configuration

Worker nodes use Cubelet/dynamicconf/conf.yaml for runtime feature toggles. This file controls node-specific behaviors such as port forwarding mode and sandbox lifecycle hooks. The schema is defined in Cubelet/pkg/config/config.go, implementing dynamic configuration loading for the Cubelet agent.

Single-Node Deployment Profiles

For development or testing environments, CubeSandbox provides simplified profiles in the configs/single-node/ directory. Files such as configs/single-node/cubemaster.yaml and configs/single-node/cubelet.yaml supply default feature flags for all-in-one deployments, merging into the runtime configuration during startup.

Common Feature Toggle Patterns

Across all configuration files, CubeSandbox employs a consistent boolean naming convention. Most feature flags follow the pattern enable_<feature_name> and accept true or false values. However, some capabilities—such as scheduler filters—use list-based toggles where you add or remove string identifiers from an enable_filters array rather than using simple boolean switches.

Practical Examples of Feature Configuration

Below are specific implementations demonstrating how to modify key features by editing the YAML configuration files.

Enable Exposed Ports

To allow Cubes to expose host ports, modify the CubeMaster configuration:

# CubeMaster/conf.yaml

cubelet_conf:
  enable_exposed_port: true
  exposed_port_list:
    - "80"
    - "443"

This setting maps to the EnableExposedPort field in CubeMaster/pkg/base/config/config.go, enabling the port exposure functionality for the cluster.

Disable API Authentication

For development environments where you want to bypass authentication checks on the CubeMaster API:

# CubeMaster/conf.yaml

auth:
  enable: false

Setting auth.enable to false disables the authentication middleware, allowing unrestricted access to the control plane endpoints. This corresponds to the authentication configuration struct in the master config source.

Enable PF Mode on Cubelet

Port Forwarding (PF) mode controls how network traffic routes through the Cubelet:

# Cubelet/dynamicconf/conf.yaml

common:
  enable_pf_mode: true

When enabled, this configures the Cubelet to use specific port forwarding logic for container networking, as processed by the configuration loader in Cubelet/pkg/config/config.go.

Activate Network Agent

For single-node deployments requiring network agent functionality:

# configs/single-node/cubelet.yaml

enable_network_agent: true

This top-level boolean enables the embedded network agent component within the Cubelet process for single-node operation profiles.

Configure Sandbox Exit Hooks

To execute custom scripts before a sandbox terminates:

# Cubelet/dynamicconf/conf.yaml

common:
  enable_sandbox_exec_cmd_before_exist: true
  sandbox_exec_cmd_before_exist:
    - sh
    - "/usr/local/cubetools/cube_exec_cmd_before_exist.sh"

This feature requires both the boolean flag and a command array specifying the executable and arguments to run during the sandbox pre-exit phase.

Customize Scheduler Filters

Control which scheduling filters the CubeMaster applies during pod placement:

# CubeMaster/conf.yaml

scheduler:
  filter:
    enable_filters:
      - "cpu"
      - "mem"
      - "template_locality"
      - "realtime_create_num"

Unlike simple boolean toggles, this feature uses the enable_filters list. Remove items from the array to disable specific scheduling constraints while keeping others active.

How Configuration Loading Works

CubeSandbox implements a structured configuration system where YAML files map directly to Go structs via yaml struct tags. When the CubeMaster starts, it reads CubeMaster/conf.yaml into the Config struct located in CubeMaster/pkg/base/config/config.go, parsing fields such as enable_exposed_port into their corresponding boolean types. Similarly, the Cubelet loads Cubelet/dynamicconf/conf.yaml using the configuration definitions in Cubelet/pkg/config/config.go.

Changes to configuration files require a service restart to take effect, as these settings are typically loaded once at startup rather than watched continuously. The single-node profile configurations in configs/single-node/ serve as base templates that merge into the active configuration during the initialization phase.

Summary

• CubeMaster features are controlled via CubeMaster/conf.yaml, including authentication, exposed ports, and scheduler filters.
• Cubelet features are managed in Cubelet/dynamicconf/conf.yaml, handling PF mode and sandbox lifecycle hooks.
• Single-node profiles in configs/single-node/ provide pre-configured defaults for development environments.
• Boolean convention: Use enable_* fields set to true or false for most features.
• List-based toggles: Scheduler filters use the enable_filters array to specify active components.
• Restart required: After editing configuration files, restart the CubeMaster or Cubelet service to apply changes.
• Source mapping: Configuration keys correspond to Go struct fields in CubeMaster/pkg/base/config/config.go and Cubelet/pkg/config/config.go.

Frequently Asked Questions

What file controls CubeMaster feature flags?

CubeMaster feature flags are defined in CubeMaster/conf.yaml. This file contains all master-level toggles including enable_exposed_port under the cubelet_conf section and enable under the auth section. The configuration structure is implemented in CubeMaster/pkg/base/config/config.go where YAML tags map directly to struct fields.

Do I need to restart services after changing config?

Yes, you must restart the corresponding service after modifying configuration files. CubeSandbox typically loads configuration once at startup rather than implementing hot-reload for most parameters. After editing CubeMaster/conf.yaml, restart the CubeMaster service; after editing Cubelet/dynamicconf/conf.yaml, restart the Cubelet process to apply the new feature toggles.

What is the naming convention for feature toggles?

CubeSandbox uses the prefix enable_ followed by a descriptive feature name for boolean toggles (snake_case). For example, enable_pf_mode, enable_exposed_port, and enable_sandbox_exec_cmd_before_exist. Scheduler filters use a different pattern with the enable_filters key accepting a list of string identifiers rather than boolean values.

Where are the default values defined?

Default configuration values appear in the sample YAML files shipped with the repository. For CubeMaster, see CubeMaster/conf.yaml; for Cubelet, see Cubelet/dynamicconf/conf.yaml. Single-node defaults reside in configs/single-node/cubemaster.yaml and configs/single-node/cubelet.yaml. These defaults are hardcoded into the Go structs in CubeMaster/pkg/base/config/config.go and Cubelet/pkg/config/config.go as fallback values when keys are omitted.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}