New to Stash? Please start here.

Function

What is Function

A complete backup or restore process may consist of several steps. For example, in order to backup a PostgreSQL database we first need to dump the database and upload the dumped file to a backend. Then we need to update the respectiveRepository and BackupSession status and send Prometheus metrics. In Stash, we call such individual steps a Function.

A Function is a Kubernetes CustomResourceDefinition(CRD) which basically specifies a template for a container that performs only a specific action. For example, postgres-backup-* function only dumps and uploads the dumped file into the backend where update-status function updates the status of respective BackupSession and Repository and sends Prometheus metrics to pushgateway based on the output of postgres-backup-* function.

When you install Stash, some Functions will be pre-installed for supported targets like databases, etc. However, you can create your own function to customize or extend the backup/restore process.

Function CRD Specification

Like any official Kubernetes resource, a Function has TypeMeta, ObjectMeta and Spec sections. However, unlike other Kubernetes resources, it does not have a Status section.

A sample Function object to backup a PostgreSQL is shown below,

apiVersion: stash.appscode.com/v1beta1
kind: Function
metadata:
  name: postgres-backup-11.2
spec:
  image: stashed/postgres-stash:11.2
  args:
  - backup-pg
  # setup information
  - --provider=${REPOSITORY_PROVIDER:=}
  - --bucket=${REPOSITORY_BUCKET:=}
  - --endpoint=${REPOSITORY_ENDPOINT:=}
  - --region=${REPOSITORY_REGION:=}
  - --path=${REPOSITORY_PREFIX:=}
  - --secret-dir=/etc/repository/secret
  - --scratch-dir=/tmp
  - --enable-cache=${ENABLE_CACHE:=true}
  - --max-connections=${MAX_CONNECTIONS:=0} # 0 indicates use default connection limit
  - --hostname=${HOSTNAME:=}
  - --backup-cmd=${backupCMD:=} # can specify dump command with either pg_dump or pg_dumpall
  - --pg-args=${args:=} # optional arguments pass to pgdump command
  - --wait-timeout=${waitTimeout:=}
  # target information
  - --namespace=${NAMESPACE:=default}
  - --appbinding=${TARGET_NAME:=}
  - --backupsession=${BACKUP_SESSION:=}
  # cleanup information
  - --retention-keep-last=${RETENTION_KEEP_LAST:=0}
  - --retention-prune=${RETENTION_PRUNE:=false}
  # output & metric information
  - --output-dir=${outputDir:=}
  volumeMounts:
  - name: ${secretVolume}
    mountPath: /etc/repository/secret
  runtimeSettings:
    resources:
      requests:
        memory: 256M
      limits:
        memory: 256M
    securityContext:
      runAsUser: 5000
      runAsGroup: 5000

A sample Function that updates BackupSession and Repository status and sends metrics to Prometheus pushgateway is shown below,

apiVersion: stash.appscode.com/v1beta1
kind: Function
metadata:
  name: update-status
spec:
  image: appscode/stash:0.10.0
  args:
  - update-status
  - --provider=${REPOSITORY_PROVIDER:=}
  - --bucket=${REPOSITORY_BUCKET:=}
  - --endpoint=${REPOSITORY_ENDPOINT:=}
  - --path=${REPOSITORY_PREFIX:=}
  - --secret-dir=/etc/repository/secret
  - --scratch-dir=/tmp
  - --enable-cache=${ENABLE_CACHE:=true}
  - --max-connections=${MAX_CONNECTIONS:=0}
  - --namespace=${NAMESPACE:=default}
  - --backupsession=${BACKUP_SESSION:=}
  - --repository=${REPOSITORY_NAME:=}
  - --invoker-kind=${INVOKER_KIND:=}
  - --invoker-name=${INVOKER_NAME:=}
  - --target-kind=${TARGET_KIND:=}
  - --target-name=${TARGET_NAME:=}
  - --output-dir=${outputDir:=}
  - --metrics-enabled=true
  - --metrics-pushgateway-url=http://stash.kube-system.svc:56789
  - --prom-job-name=${PROMETHEUS_JOB_NAME:=}
  volumeMounts:
  - mountPath: /etc/repository/secret
    name: ${secretVolume}

Here, we are going to describe the various sections of a Function crd.

Function Spec

A Function object has the following fields in the spec section:

spec.image

spec.image specifies the docker image to use to create a container using the template specified in this Function.

spec.command

spec.command specifies the commands to be executed by the container. Docker image’s ENTRYPOINT will be executed if no commands are specified.

spec.args

spec.args specifies a list of arguments that will be passed to the entrypoint. You can templatize this section using envsubst style variables. Stash will resolve all the variables before creating the respective container. A variable should follow the following patterns:

• ${VARIABLE_NAME:=default-value}
• ${VARIABLE_NAME:=}

In the first case, if Stash can’t resolve the variable, the default value will be used in place of this variable. In the second case, if Stash can’t resolve the variable, an empty string will be used to replace the variable.

Stash Provided Variables

Stash operator provides the following built-in variables based on BackupConfiguration, BackupSession, RestoreSession, Repository, Task, Function, BackupBlueprint etc.

If you want to use a variable that is not present this table, you have to provide its value in spec.task.params section of BackupConfiguration crd.

spec.workDir

spec.workDir specifies the container’s working directory. If this field is not specified, the container’s runtime default will be used.

spec.ports

spec.ports specifies a list of the ports to expose from the respective container that will be created for this function.

spec.volumeMounts

spec.volumeMounts specifies a list of volume names and their mountPath that will be mounted into the container that will be created for this function.

spec.volumeDevices

spec.volumeDevices specifies a list of the block devices to be used by the container that will be created for this function.

spec.runtimeSettings

spec.runtimeSettings.container allows to configure runtime environment of a backup job at container level. You can configure the following container level parameters:

spec.podSecurityPolicyName

If you are using a PSP enabled cluster and the function needs any specific permission then you can specify the PSP name using spec.podSecurityPolicyName field. Stash will add this PSP in the respective RBAC roles that will be created for this function.

Note that Stash operator can’t give permission to use a PSP to a backup job if the operator itself does not have permission to use it. So, if you want to specify PSP name in this section, make sure to add that in stash-operator ClusterRole too.

Next Steps

• Learn how to use Function to create a Task from here.