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

> Learn how to enable or disable features in CubeSandbox by editing boolean fields in YAML config files and restarting services. A complete guide for TencentCloud CubeSandbox.

- Repository: [Tencent Cloud/CubeSandbox](https://github.com/TencentCloud/CubeSandbox)
- Tags: how-to-guide
- Published: 2026-07-13

---

**You can enable or disable features in CubeSandbox by modifying boolean `enable_*` fields in YAML configuration files such as [`CubeMaster/conf.yaml`](https://github.com/TencentCloud/CubeSandbox/blob/main/CubeMaster/conf.yaml) and [`Cubelet/dynamicconf/conf.yaml`](https://github.com/TencentCloud/CubeSandbox/blob/main/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`](https://github.com/TencentCloud/CubeSandbox/blob/main/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`](https://github.com/TencentCloud/CubeSandbox/blob/main/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`](https://github.com/TencentCloud/CubeSandbox/blob/main/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`](https://github.com/TencentCloud/CubeSandbox/blob/main/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`](https://github.com/TencentCloud/CubeSandbox/blob/main/configs/single-node/cubemaster.yaml) and [`configs/single-node/cubelet.yaml`](https://github.com/TencentCloud/CubeSandbox/blob/main/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:

```yaml

# 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`](https://github.com/TencentCloud/CubeSandbox/blob/main/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:

```yaml

# 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:

```yaml

# 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`](https://github.com/TencentCloud/CubeSandbox/blob/main/Cubelet/pkg/config/config.go).

### Activate Network Agent

For single-node deployments requiring network agent functionality:

```yaml

# 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:

```yaml

# 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:

```yaml

# 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`](https://github.com/TencentCloud/CubeSandbox/blob/main/CubeMaster/conf.yaml) into the `Config` struct located in [`CubeMaster/pkg/base/config/config.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/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`](https://github.com/TencentCloud/CubeSandbox/blob/main/Cubelet/dynamicconf/conf.yaml) using the configuration definitions in [`Cubelet/pkg/config/config.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/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`](https://github.com/TencentCloud/CubeSandbox/blob/main/CubeMaster/conf.yaml), including authentication, exposed ports, and scheduler filters.
- **Cubelet features** are managed in [`Cubelet/dynamicconf/conf.yaml`](https://github.com/TencentCloud/CubeSandbox/blob/main/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`](https://github.com/TencentCloud/CubeSandbox/blob/main/CubeMaster/pkg/base/config/config.go) and [`Cubelet/pkg/config/config.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/Cubelet/pkg/config/config.go).

## Frequently Asked Questions

### What file controls CubeMaster feature flags?

CubeMaster feature flags are defined in [`CubeMaster/conf.yaml`](https://github.com/TencentCloud/CubeSandbox/blob/main/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`](https://github.com/TencentCloud/CubeSandbox/blob/main/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`](https://github.com/TencentCloud/CubeSandbox/blob/main/CubeMaster/conf.yaml), restart the CubeMaster service; after editing [`Cubelet/dynamicconf/conf.yaml`](https://github.com/TencentCloud/CubeSandbox/blob/main/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`](https://github.com/TencentCloud/CubeSandbox/blob/main/CubeMaster/conf.yaml); for Cubelet, see [`Cubelet/dynamicconf/conf.yaml`](https://github.com/TencentCloud/CubeSandbox/blob/main/Cubelet/dynamicconf/conf.yaml). Single-node defaults reside in [`configs/single-node/cubemaster.yaml`](https://github.com/TencentCloud/CubeSandbox/blob/main/configs/single-node/cubemaster.yaml) and [`configs/single-node/cubelet.yaml`](https://github.com/TencentCloud/CubeSandbox/blob/main/configs/single-node/cubelet.yaml). These defaults are hardcoded into the Go structs in [`CubeMaster/pkg/base/config/config.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/CubeMaster/pkg/base/config/config.go) and [`Cubelet/pkg/config/config.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/Cubelet/pkg/config/config.go) as fallback values when keys are omitted.