Qbec

The --app-tag command-line argument allows you to scope qbec objects to a specific application, environment, and tag. This is used to ensure that branch builds run in their own 'scope' and do not interfere with mainline builds or trigger unintended Garbage Collection (GC) of mainline objects.

When using --app-tag, qbec provides the following:

• Scoped GC: Garbage Collection is restricted to the specific tag, preventing it from deleting mainline or other tagged objects.
• Jsonnet Variable qbec.io/tag: The tag value is exposed as an external variable so components can use it to create unique names.
• Jsonnet Variable qbec.io/defaultNs: The name of the default namespace used for the run is exposed. If namespaceTagSuffix is enabled, this value can be automatically suffixed with the tag.

qbec apply --app-tag=foo env

When using param sub-commands, qbec expects your runtime configuration file (e.g., params.libsonnet) to return a JSON object structured by component names. The object must contain a top-level components key, with each subsequent key representing a component name and its associated configuration parameters.

Your configuration must also be able to handle the baseline environment, represented by the underscore _ character.

{
  "components": {
    "component1": {
      "param1": "value1",
      "param2": "value2"
    },
    "component2": {
      "param1": "value1"    
    }
  }
}

qbec automatically provides a special baseline environment named _. This environment does not represent a real cluster and is used for local commands that do not affect a cluster, such as:

• show
• component subcommands
• param subcommands

When running commands against the baseline environment, your code should be able to handle the _ environment name and return appropriate default values.

By default, qbec includes all supported files found in the application's components directory. You can refine this list in qbec.yaml to control which components are applied to specific environments:

• Default Exclusions: You can supply a list of components that are excluded from all environments by default. These must be explicitly included in an environment to be deployed.
• Explicit Inclusion/Exclusion: You can provide per-environment lists to explicitly include or exclude specific components.

An environment represents a target cluster, defined by a server URL and an optional defaultNamespace. qbec supports two primary deployment models:

1. One environment per cluster: Every environment is a separate cluster. You can create cluster-scoped objects and objects in multiple namespaces.
2. Multiple environments per cluster: Multiple environments share a single cluster but use different namespaces. In this model, you should only create namespace-scoped objects and omit namespace metadata in the object definitions to allow qbec to manage them via the environment's defaultNamespace.

qbec uses the qbec.io/env external variable to determine the current environment.

• For param sub-commands: qbec strictly uses the runtime configuration file to resolve parameters based on the value of qbec.io/env.
• For other commands: qbec sets the qbec.io/env variable to the environment name. It is your responsibility to ensure your component code correctly uses this variable to configure itself.

To simplify the setup of these files and ensure the baseline environment (_) is correctly handled, you can use the qbec init command to scaffold a recommended file organization.

Components are the source code representations of Kubernetes objects. You typically group related objects (e.g., a microservice's Deployment, Service, and ConfigMap) into a single component.

Components can be loaded from:

• jsonnet files: These allow for customization of object definitions across different environments.
• json files
• yaml files
• helm charts: qbec can load objects from Helm charts, often using jsonnet libraries to produce them.