Parameters

The parent key for all of the following parameters is system_upgrade_controller.

namespace

type

string
default

syn-system-upgrade-controller

The namespace in which to deploy this component. When parameter plans_only is set to true, the component expects that the provided namespace exists and a SUC instance is deployed in the given namespace.

service_account

type

string
default

system-upgrade

The name of the service account for System Upgrade Controller. When option plans_only is set to true, the component expects that a service account with the given name exists in the target namespace.

plans_only

type

boolean
default

false

Whether to install the manifests for System Upgrade Controller. If set to true only plan manifests will be applied. Plans must be installed in the same namespace as the controller.

controller_threads

type

string
default

2

The amount of threads System Upgrade Controller will run.

plan_polling_interval

type

string
default

15m

The interval time the System Upgrade Controller check for plan execution.

affinity

type

hash
default

{}

Affinity configuration for the System Upgrade Controller pod.

Example:

parameters:
  system_upgrade_controller:
    affinity:
      nodeAffinity:
        requiredDuringSchedulingIgnoredDuringExecution:
          nodeSelectorTerms:
          - matchExpressions:
            - key: node-role.kubernetes.io/controlplane
              operator: In
              values:
              - "true"

debug_logging

type

string
default

false

If the System Upgrade Controller will run in debug mode.

floodgate_url

type

string
default

floodgate.syn.vshn.net/

The floodgate service URL being used.

Floodgate is a Syn project providing individual System Upgrade Controller channels based on time conditions.

disable_grafana_dashboard

type

boolean
default

false

If true it disables the Grafana dashboard.

This is intended to be used when Grafana components aren’t fully installed or the dashboard isn’t required at all.

job_backoff_limit

type

string
default

3

The backoff limit for System Upgrade Controller jobs.

job_deadline_seconds

type

string
default

900

The deadline for System Upgrade Controller jobs in seconds.

job_image_pull_policy

type

string
default

Always

The image pull policy for System Upgrade Controller jobs.

job_kubectl_image

type

string
default

rancher/kubectl:v1.17.0

The kubectl image the System Upgrade Controller uses in the jobs.

job_privileged

type

string
default

true

If the System Upgrade Controller job does run in privileged mode.

job_ttl_after_finish

type

string
default

900

The time in seconds the System Upgrade Controller jobs are kept after they’re completed.

plans

type

dict
default

{}

This parameter allows users to configure one or more System Upgrade Controller Plan resources.

Each entry in the dict corresponds to one Plan resource. Dict keys are used as the name of the resulting Plan resource. The dict value is expected to be another dict. The component supports keys spec, floodgate, label_selectors and tolerations in the value dict.

Plans can be removed by setting the value of the dict entry to null.

plans.<P>.spec

type

dict
default 
nodeSelector:
  matchExpressions:
    <from plans.<P>.label_selectors>
serviceAccountName: <params.service_account>
tolerations:
  <from plans.<P>.tolerations>
drain:
  force: true

This parameter is mandatory. A minimal configuration requires fields upgrade.image and upgrade.command to be set.

This parameter is merged with the predefined configuration shown above to form the Plan resource’s spec field. Configurations in the parameter override values in the default. Configurations given in other fields in the plan configuration may override values provided in this parameter. See the following sections for details.

The component accepts both string and array values for spec.upgrade.command. If a string value is given, it’s transformed into an array with a single member.

See the System Upgrade Controller documentation for supported configurations.

plans.<P>.floodgate

type

dict
supported keys

url, basepath, day, hour

This parameter is required unless either field channel or field version is present in plan parameter spec. This parameter can be used to instruct the component to construct a Floodgate-based value for the plan’s channel. If field channel or field version in key plans.<P>.spec is set, configuration provided in this parameter has no effect.

The supported keys in this parameter have the following effects:

url

The base URL of the Floodgate instance. This key is optional. If it’s not present, the value of component parameter floodgate_url is used in the resulting channel value.

basepath

The base path appended to the Floodgate URL. This key is optional. If it’s not present, the component uses window as base path.

day

The day of the week on which to start the upgrade. This should be a number between 0 (Sunday) and 6 (Saturday).

hour

The hour in the day on which to start the upgrade This should be a number between 0 and 23.

See the Floodgate documentation for details on how Floodgate works.

plans.<P>.push_gateway

type

string

A Prometheus push gateway address as DNS name or IP. This parameter is optional. If present, the value of this parameter is appended to any arbitrary arguments given in the plan’s spec.upgrade.args. If you need more complex configuration, please provide any arguments to the upgrade command directly in spec.upgrade.args and omit this parameter

plans.<P>.label_selectors

type

dict

Specify a label selector according to which nodes to upgrade are selected. This parameter is mandatory. The System Upgrade Controller will add and manage label plan.upgrade.cattle.io/P for a plan named P to all nodes selected by the label selectors. It will set the value of that label to the SHA256 hash of the Docker image used for the upgrade. It’s considered best practice to use that label as the label selector for the plan.

The component will transform the provided dict into a list of Kubernetes label selector matchExpressions. Each dict entry is transformed into a LabelSelectorRequirement. The value of each entry used as the LabelSelectorRequirement and the key of the entry is set as the value for field key.

The resulting list of LabelSelectorRequirements is assigned to key spec.nodeSelector.matchExpressions in the Plan resource.

See the Kubernetes API documentation for supported fields in LabelSelectorRequirement.

plans.<P>.tolerations

type

dict

Specify Kubernetes tolerations for the upgrade job. This parameter is optional. If omitted, no tolerations are configured on the plan.

The component transforms the provided dict into a list of Kubernetes tolerations. Each dict entry is transformed into a Toleration by the component. The entry’s value is used as a Toleration and the entry’s key is set as value for field key.

The component assigns the resulting list of tolerations to field spec.tolerations in the Plan.

See the Kubernetes API documentation for supported fields in Toleration.

Example Plan

In this example, we specify a taint for etcd or control plane components so that the upgrade jobs can be scheduled on nodes hosting control plane or etcd components.

parameters:
  system_upgrade_controller:
    plans:
      system-upgrade-focal: (1)
        spec: (2)
          concurrency: 1
          upgrade:
            image: docker.io/projectsyn/suc-ubuntu-focal
            command: /scripts/run.sh
        push_gateway: 10.43.209.108:9091
        floodgate:
          hour: 22
          day: 2
        label_selectors:
          plan.upgrade.cattle.io/system-upgrade-focal: (1)
            operator: Exists
        tolerations:
          node-role.kubernetes.io/controlplane:
            operator: Exists
          node-role.kubernetes.io/etcd:
            operator: Exists
1 We recommend to use matching label selector and plan name. This minimizes the amount of labels added to nodes by the System Upgrade Controller.
2 Check the official documentation for supported fields in spec.

This configuration results in the following Plan object:

apiVersion: upgrade.cattle.io/v1
kind: Plan
metadata:
  name: system-upgrade-focal
spec:
  channel: https://floodgate.syn.vshn.net/window/2/22
  concurrency: 1
  drain:
    force: true
  nodeSelector:
    matchExpressions:
      - key: plan.upgrade.cattle.io/system-upgrade-focal
        operator: Exists
  serviceAccountName: system-upgrade
  tolerations:
    - key: node-role.kubernetes.io/controlplane
      operator: Exists
    - key: node-role.kubernetes.io/etcd
      operator: Exists
  upgrade:
    args:
      - 10.43.209.108:9091
    command:
      - /scripts/run.sh
    image: docker.io/projectsyn/suc-ubuntu-focal