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

Imperative mode πŸ”—︎

The main purpose of the imperative mode is to install Supertubes, 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 Supertubes 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 Supertubes, 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 is not suitable for automation. CD systems typically require Helm charts, Kustomize, or pure YAML resources to operate with.

Using the imperative mode πŸ”—︎

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

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 Supertubes operator, see Operator mode.

  • istio: supertubes istio [install|uninstall]
  • mirror-maker2: supertubes mirror-maker2 [install|uninstall]
  • prometheus: supertubes prometheus [install|uninstall]
  • supertubes: supertubes [install|uninstall]
  • zookeeper: supertubes zookeeper [install|uninstall]

Note: the supertubes install -a command assumes that there is a default storage class available on the cluster, to provision the needed volumes. If your Kubernetes environment doesn’t have a default storage class, then the CRs deployed by Supertubes must be adjusted in order to work in your environment. In that case, request a demo and describe your use case so we can guide you through the configuration details as part of the demo.

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. Supertubes uses the native reconciler, which 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.

Compared to kubectl apply, this solution adds ordering, and allows executing custom logic if required. Also, it removes resources that are not present in the configuration 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 Supertubes 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. Retrieve the current Supertubes Application Manifest from your Kubernetes cluster:

    kubectl get applicationmanifests applicationmanifest -o yaml > /var/tmp/appmanifest.yml
    
  2. Edit the configuration settings you want to apply in the downloaded YAML file. For details on the configuration settings, see the ApplicationManifest Custom Resource.

    Make sure that the indentation is correct, otherwise your changes will not be applied correctly.

    The following example sets a new password for Grafana.

    apiVersion: supertubes.banzaicloud.io/v1beta1
    kind: ApplicationManifest
    metadata:
    name: applicationmanifest-sample
    spec:
    istioOperator:
      enabled: true
      createDefaultMesh: true
      namespace: istio-system
    kafkaOperator:
      enabled: true
      namespace: kafka
    supertubes:
      enabled: true
      namespace: supertubes-system
    monitoring:
      grafanaDashboards:
        enabled: true
      prometheusOperator:
        enabled: true
        namespace: supertubes-system
        valuesOverride: |-
          grafana:
            adminPassword: my-new-password
    kafkaMinion:
      enabled: true
    zookeeperOperator:
      enabled: true
      createDefaultCluster: true
      namespace: zookeeper
    
  3. Run the following command to apply the changes:

    supertubes reconcile --from-file <path-to-file> -n my-namespace -c <path-to-kubeconfig-file>
    

    Alternatively, you can also use the following command:

    cat <path-to-file> | supertubes reconcile -n my-namespace -c <path-to-kubeconfig-file>
    
  4. 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 (also called declarative mode) follows the familiar operator pattern. In operator mode, Supertubes watches events on the ApplicationManifest 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 Supertubes 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 Supertubes 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 Supertubes in operator mode, complete the following steps. In this scenario, the reconcile flow runs on the Kubernetes cluster as an operator that watches the ApplicationManifest custom resources. Any changes made to the watched custom resource triggers the reconcile flow.

  1. Run the following commands to install the Supertubes operator.

    helm repo add banzaicloud-stable https://kubernetes-charts.banzaicloud.com/
    helm install banzaicloud-stable/supertubes-control-plane
    
  2. Deploy the ApplicationManifest CR to the Kubernetes cluster using the kubectl apply command (either manually, or using your CI/CD system). The status of the ApplicationManifest provides information on the progress and status of the deployment of the enabled components, as well as the overall status of the reconcile flow.

Example: Update the settings of a component πŸ”—︎

  1. The following example sets a new password for Grafana.

    apiVersion: supertubes.banzaicloud.io/v1beta1
    kind: ApplicationManifest
    metadata:
    name: applicationmanifest-sample
    spec:
    istioOperator:
      enabled: true
      createDefaultMesh: true
      namespace: istio-system
    kafkaOperator:
      enabled: true
      namespace: kafka
    supertubes:
      enabled: true
      namespace: supertubes-system
    monitoring:
      grafanaDashboards:
        enabled: true
      prometheusOperator:
        enabled: true
        namespace: supertubes-system
        valuesOverride: |-
          grafana:
            adminPassword: my-new-password
    kafkaMinion:
      enabled: true
    zookeeperOperator:
      enabled: true
      createDefaultCluster: true
      namespace: zookeeper
    

    You can apply it with the following command:

    kubectl apply -f path/to/grafana-password.yaml
    
  2. In the status section you can see that the status for monitoring has changed to Reconciling.

    ...
    status:
      components:
        istioOperator:
          meshStatus: Available
          status: Available
        kafkaOperator:
          status: Available
        monitoring:
          status: Reconciling
        supertubes:
          status: Available
        zookeeperOperator:
          clusterStatus: Available
          status: Available
      status: Reconciling
    
  3. After successfully applying the new configuration, the status changes to Available.

    ...
    status:
      components:
        istioOperator:
          meshStatus: Available
          status: Available
        kafkaOperator:
          status: Available
        monitoring:
          status: Available
        supertubes:
          status: Available
        zookeeperOperator:
          clusterStatus: Available
          status: Available
      status: Succeeded
    

Uninstall the Supertubes Control Plane πŸ”—︎

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

supertubes uninstall -a
helm del --purge <supertubes-control-plane-release-name>

When to use operator mode πŸ”—︎

Imperative mode is best suited for Day 0 and Day 1 operations, while declarative mode is best for Day 2, production usage. We recommend to start in imperative mode to familiarize yourself with all the CRs, deployments, and configurations. Then experiment: tweak the various CRs, deployments, and configurations to suit your environments and your needs. When you are finished, redeploy everything in declarative mode using a GitOps flow.

The ApplicationManifest Custom Resource πŸ”—︎

Supertubes installs the ApplicationManifest Custom Resource with the following default values.

How you can modify this resource depends on whether you are using Supertubes in imperative mode or operator mode.

apiVersion: supertubes.banzaicloud.io/v1beta1
kind: ApplicationManifest
metadata:
  name: supertubes-apps
spec:
  istioOperator:  # Istio operator and Istio mesh related settings.
    enabled: true  # Whether to deploy or remove Istio operator component. Defaults to true.

    # Whether to create an Istio mesh. Defaults to true. For an Istio mesh with
    # custom settings set this to false and create a https://github.com/banzaicloud/istio-operator/blob/release-1.5/config/samples/istio_v1beta1_istio.yaml custom resource with your settings.
    createDefaultMesh: true
    namespace: istio-system # The namespace to deploy Istio operator into. Defaults to istio-system.
    # Settings override in YAML format. For the list of overrideable settings see https://github.com/banzaicloud/istio-operator/blob/release-1.5/deploy/charts/istio-operator/values.yaml
    valuesOverride:
  kafkaOperator: # Kafka operator related settings.  
    enabled: true # Whether to deploy or remove Kafka operator component. Defaults to true.
    namespace: kafka # The namespace to deploy Kafka operator into. Defaults to kafka.
    valuesOverride:
  supertubes: # Supertubes backend related settings.
    enabled: true # Whether to deploy or remove Supertubes backend component. Defaults to true.
    namespace: supertubes-system # The namespace to deploy Supertubes backend into. Defaults to supertubes-system.
    # Settings override in YAML format. For the list of overrideable settings see https://banzaicloud.com/docs/supertubes/overview/
    valuesOverride:
  monitoring: # Monitoring related settings
    grafanaDashboards: # Grafana dashboards related settings
      enabled: true # Whether to deploy ConfigMaps with Grafana dashboards for the components.
      label: # The label to apply to the Grafana dashboard ConfigMaps. It defaults to "app.kubernetes.io/supertubes_managed_grafana_dashboard"
    prometheusOperator: # Prometheus operator related settings
      enabled: true # Whether to deploy or remove Prometheus operator component. Defaults to true.
      namespace: supertubes-system # The namespace to deploy Prometheus operator into. Defaults to supertubes-system.
      # Settings override in YAML format. For the list of overrideable settings see Prometheus operator Helm chart version 8.11.2
      valuesOverride:
  kafkaMinion: # Kafka Minion related settings
    enabled: true # Whether to deploy Kafka Minion for all Kafka clusters.
    # Settings override in YAML format. For the list of overrideable settings see Kafka Minion Helm chart at https://github.com/banzaicloud/kafka-minion-helm-chart
    valuesOverride:
  zookeeperOperator: # Zookeeper operator and Zookeeper cluster related settings
    enabled: true # Whether to deploy or remove Zookeeper operator component. Defaults to true.
    # Whether to create a default 3 ensemble Zookeeper cluster. Defaults to true. For a Zookeeper cluster with custom settings set this to false and create a https://github.com/pravega/zookeeper-operator/tree/v0.2.6#deploy-a-sample-zookeeper-cluster custom resource with your settings.
    createDefaultCluster: true
    namespace: zookeeper # The namespace to deploy Zookeeper operator into. Defaults to zookeeper.
    # Settings override in YAML format. For the list of overrideable settings see https://github.com/pravega/zookeeper-operator/blob/v0.2.6/charts/zookeeper-operator/values.yaml
    valuesOverride:

The ApplicationManifest custom resource is the owner of the deployed components. If you remove the custom resource, the Kubernetes Garbage Collector will remove all deployed components.