To support the different use-cases from Day 0 to Day 2 operations, Backyards has different modes of operation. The same binary can act as:

Imperative mode πŸ”—︎

The main purpose of the imperative mode is to install Backyards, get you started, and help you experiment with the various components. You can access only a small subset of the available configuration options and features (mostly just the default settings and some of the most important configuration flags) to avoid getting overloaded with command line flags.

Most notably, you can install and delete Backyards from the command line. Internally, the install and delete commands change the component-specific parts of the main configuration, then trigger the reconciliation of the affected components.

Other commands do not necessarily change the main configuration, nor trigger reconciliation of any component. Such commands create dynamic resources which are out of scope for the reconcilers, but are convenient for getting started without having to leave the CLI.

Once you are finished experimenting with Backyards, the recommended way forward is to start using the reconcile command, and apply all configuration through the custom resource directly. This is analogous to how you use kubectl create and then switch to using kubectl apply when you already have a full configuration and just want to apply changes incrementally. If you are an experienced Kubernetes user, you probably skip the imperative mode and start using the reconcile command from the beginning.

The drawback of the imperative mode is that there is no overall state of components, so it can’t tell what has already been installed.

Also, it it not suitable for automation. CD systems typically require Helm charts, Kustomize, or pure YAML resources to operate with. Although the imperative commands of Backyards have a --dump-resources flag that generates YAML files instead of applying them, you would still have to run the install command locally for each component, and commit the generated resources into version control. The CD workflow would then have to specify sequential steps for each component separately, making the whole flow difficult to extend over time.

Using the imperative mode πŸ”—︎

To use Backyards in imperative mode, install the backyards-cli command-line tool, then use its commands to install Backyards and perform other actions. For a list of available commands, see the CLI reference.

Note: You can also configure many aspects of your service mesh using the Backyards web interface. To access the web interface run the backyards dashboard command (if your KUBECONFIG file is set properly, the backyards dashboard command automatically performs the login).

Install/Uninstall components πŸ”—︎

The following components can be installed/uninstalled individually. The -a flag installs/uninstalls them all. For details on installing and uninstalling the Backyards operator, see Operator mode.

Reconciler mode πŸ”—︎

Reconciler mode is a declarative CLI mode. The reconcile command is a one-shot version of an operator’s reconcile flow. It executes the component reconcilers in order, and can decide whether they require another reconciliation round, or are already finished. Reconciling can apply new configuration, and remove disabled components from the system.

Note: In this mode, the operator is not installed on the cluster. The controller code runs from the CLI on the client side.

A component can be anything that receives the whole configuration, understands its own part from it to configure itself, and is able to delete its managed resources when disabled or removed. Backyards uses two different implementations:

  • The native reconciler triggers a β€œresource builder” to create Kubernetes resources along with their desired state (present or absent) based on the configuration of the component. Such resource builders create CRDs, RBAC, and a Deployment resource to be able to run an operator.

  • The other implementation is the Helm reconciler that basically acts as a Helm operator. It installs and upgrades an embedded chart if it has changed, or uninstalls it if it has been removed from the main configuration.

Compared to kubectl apply, these solutions add ordering, and allow executing custom logic if required. Also, they remove resources that are not present in the config anymore. The CLI in this case executes the control logic as well.

Compared to terraform, the dependencies are managed in a predefined execution order and have static binding using deterministic names. Lower performance, but easier to follow. Remote state is the CR saved to the API server.

Using the reconciler mode πŸ”—︎

To use Backyards in reconciler mode, complete the following steps. In this scenario, the manifest is read from a file, allowing you to declaratively provide custom configuration for the various components.

  1. Login to your Backyards installation.

  2. Prepare the configuration settings you want to apply in a YAML file, and run the following command. For details on the configuration settings, see the ControlPlane Custom Resource.

    backyards reconcile --from-file <path-to-file>
    
  3. The settings applied to the components are the result of merging the default settings + valuesOverride + managed settings. You cannot change the managed settings to avoid misconfiguration and possible malfunction.

Operator mode πŸ”—︎

The operator mode follows the familiar operator pattern. In operator mode, Backyards watches events on the ControlPlane Custom Resource, and triggers a reconciliation for all components in order, the same way you can trigger the reconcile command locally.

Note: Unlike in the declarative CLI mode, in operator mode the Backyards operator is running inside Kubernetes, and not on a client machine. This naturally means that this mode is exclusive with the install, delete, and reconcile commands.

Using the operator mode is the recommended way to integrate the Backyards installer into a Kubernetes-native continuous delivery solution, for example, Argo, where the integration boils down to applying YAML files to get the installer deployed as an operator.

Existing configurations managed using the reconcile command work out-of-the box after switching to the operator mode.

Using the operator mode πŸ”—︎

To use Backyards in operator mode, complete the following steps. In this scenario, the reconcile flow runs on the Kubernetes cluster as an operator that watches the ControlPlane custom resources. Any changes made to the watched custom resource triggers the reconcile flow.

  1. Login to your Backyards installation.

  2. Run the following commands to install the Backyards operator.

    helm repo add banzaicloud-stable https://kubernetes-charts.banzaicloud.com/
    helm install --name=backyards-operator --namespace=backyards-system banzaicloud-stable/backyards-operator
    
  3. Activate the Backyards operator on your cluster:

    backyards operator reconcile
    

Uninstall the operator πŸ”—︎

If have used the Backyards operator on a cluster and want to delete Backyards and the operator, run the following commands.

backyards uninstall -a
helm del --purge backyards-operator

The ControlPlane Custom Resource πŸ”—︎

Backyards installs the ControlPlane Custom Resource with the following default values.

apiVersion: backyards.banzaicloud.io/v1alpha1
kind: ControlPlane
metadata:
  name: backyards
spec:
  backyards:
    enabled: true
    auditSink:
      enabled: false
    auth:
      mode: impersonation
    certManager:
      enabled: true
    impersonation:
      enabled: true
    namespace: backyards-system
    releaseName: backyards
    useIstioResources: true
    web:
      enabled: true
  canaryOperator:
    enabled: true
    namespace: backyards-canary
    prometheusURL: ""
    releaseName: ""
  certManager:
    enabled: true
    namespace: cert-manager
  istioOperator:
    enabled: true
    istioCRRef:
      name: mesh
      namespace: istio-system
    namespace: istio-system
  nodeExporter:
    enabled: true
    namespace: backyards-system
    psp:
      enabled: false
    rbac:
      enabled: true