Overview

This feature is still considered experimental and might change in future releases.

Minishift allows to extend the vanilla OpenShift setup provided by cluster up with an add-on mechanism.

Add-ons are directories that contain a text file with the .addon extension. The directory can also contain other resource files such as JSON template files. However, only one .addon file is allowed per add-on.

The following example shows the contents of an add-on file, including the name and description of the add-on, additional metadata, and the actual add-on commands to apply.

Example: anyuid add-on definition file
# Name: anyuid                                                                          (1)
# Description: Allows authenticated users to run images under a non pre-allocated UID   (2)
# Required-vars: ACME_TOKEN                                                             (3)

oc adm policy add-scc-to-group anyuid system:authenticated                              (4)
1 (Required) Name of the add-on.
2 (Required) Description of the add-on.
3 (Optional) Comma separated list of required interpolation variables. See Variable Interpolation
4 Actual add-on command. In this case, the command executes the oc binary.
Comment lines, starting with the '#' character, can be inserted at anywhere in the file.

Enabled add-ons are applied during minishift start, immediately after the initial cluster provisioning is successfully completed.

Add-on Commands

This section describes the commands that an add-on file can contain. They are forming a mini-DSL for Minishift add-ons:

ssh

If the add-on command starts with ssh, you can run any command within the Minishift-managed VM. This is similar to running minishift ssh and then executing any command on the VM. For more information about the minishift ssh command usage, see Connecting to the Minishift VM with SSH.

oc

If the add-on command starts with oc, it uses the oc binary that is cached on your host to execute the specified oc command. This is similar to running oc --as system:admin …​ from the command-line.

The oc command is executed as system:admin.
openshift

If the add-on command starts with openshift, you can run the openshift binary within the container that runs OpenShift. This means that any file parameters or other system-specific parameters must match the environment of the container instead of your host.

docker

If the add-on command starts with docker, it executes a docker command against the Docker daemon within the Minishift VM. This is the same daemon on which the single-node OpenShift cluster is running as well. This is similar to running eval $(minishift docker-env) on your host and then executing any docker command. See also minishift docker-env.

echo

If the add-on command starts with echo, the arguments following the echo command are printed to the console. This can be used to provide additional feedback during add-on execution.

sleep

If the add-on command starts with sleep, it waits for the specified number of seconds. This can be useful in cases where you know that a command such as oc might take a few seconds before a certain resource can be queried.

Trying to use an undefined command will cause an error when the add-on gets parsed.

Variable Interpolation

Minishift allows the use of variables within the add-on commands. Variables have the format {<variable-name>}. The following example shows how the OpenShift routing suffix can be interpolated into an openshift command to create a new certificate as part of securing the OpenShift registry. The used variable {routing-suffix} is part of the built-in add-on variables.

Example: Usage of the routing-suffix variable
$ openshift admin ca create-server-cert \
  --signer-cert=/var/lib/origin/openshift.local.config/master/ca.crt \
  --signer-key=/var/lib/origin/openshift.local.config/master/ca.key \
  --signer-serial=/var/lib/origin/openshift.local.config/master/ca.serial.txt \
  --hostnames='docker-registry-default.#{routing-suffix},docker-registry.default.svc.cluster.local,172.30.1.1' \
  --cert=/etc/secrets/registry.crt \
  --key=/etc/secrets/registry.key

Built-in Variables

There exist several built-in variables which are available for interpolation at all times. The following table shows these variables.

Table 1. Supported built-in add-on variables
Variable Description

ip

IP of the Minishift VM.

routing-suffix

OpenShift routing suffix for the application.

addon-name

Name of the current add-on.

Dynamic Variables

The commands minishift start as well as minishift addons apply also provide an --addon-env flag which allows to dynamically pass variables for interpolation, for example:

$ minishift addons apply --addon-env PROJECT_USER=john acme

The --addon-env flag can be specified multiple times to define more than one variables for interpolation.

Specifying dynamic variables also works in conjunction with setting persistent configuration values.

$ minishift config set addon-env PROJECT_USER=john
$ minishift addons apply acme
Multiple variables need to be comma separated when the minishift config set is used.

There is also the possibility to dynamically interpolate a variable with the value of an environment variable at the time the add-on gets applied. For this the variable value needs to be prefixed with env.

$ minishift config set addon-env PROJECT_USER=env.USER        (1)
$ minishift addons apply acme                                 (2)
1 Using the env prefix ensures that instead of literally replacing '#{PROJECT_USER}' with 'env.USER', the value of the environment variable USER is used. If the environment variable is not set not, interpolation does not occur.
2 When the add-on is applied, each occurrence of #{PROJECT_USER} within an add-on command gets replaced with the value of the environment variable USER.

As add-on developer, you can enforce that a variable value is provided when the add-on gets applied by adding the varaible name to the Required-Vars metadata header. Multiple variables need to be comma separated.

# Name: acme
# Description: ACME add-on
# Required-Vars: PROJECT_USER

Default Add-ons

Minishift provides a set of built-in add-ons that offer some common OpenShift customization to assist with development. To install the default add-ons, run:

$ minishift addons install --defaults

This command extracts the default add-ons to the add-on installation directory $MINISHIFT_HOME/addons. To view the list of installed add-ons, you can then run:

$ minishift addons list --verbose=true

This command prints a list of installed add-ons. You should at least see the anyuid add-on listed. This is an important add-on that allows you to run images that do not use a pre-allocated UID. By default, this is not allowed in OpenShift.

Enabling and Disabling Add-ons

Add-ons are enabled with the minishift addons enable command and disabled with the minishift addons disable command. Enabled add-ons automatically get executed during minishift start.

The following examples show how to enable and disable the anyuid add-on.

Example: Enabling the anyuid add-on
$ minishift addons enable anyuid
Example: Disabling the anyuid add-on
$ minishift addons disable anyuid

Add-on Priorities

When you enable an add-on, you can also specify a priority, which determines the order that the add-ons are applied.

The following example shows how to enable the registry add-on with a higher priority value.

Example: Enabling the registry add-on with priority
$ minishift addons enable registry --priority=5

The add-on priority attribute determines the order in which add-ons are applied. By default, an add-on has the priority 0. Add-ons with a lower priority value are applied first.

In the following example, the anyuid, registry, and eap add-ons are enabled with the respective priorities of 0, 5 and 10. This means that anyuid is applied first, followed by registry, and lastly the eap add-on.

Example: List command output with explicit priorities
$ minishift addons list
- anyuid         : enabled    P(0)
- registry       : enabled    P(5)
- eap            : enabled    P(10)
If two add-ons have the same priority the order in which they are getting applied is not determined.

Applying Add-ons

Add-ons can be explicitly executed with the minishift addons apply command. You can use the apply command for both enabled and disabled add-ons. To apply multiple add-ons with a single command, specify add-on names separated by space.

The following example shows how to explicitly apply the anyuid and the admin-user add-ons.

Example: Applying anyuid and admin-user add-ons
$ minishift addons apply anyuid admin-user

Writing Custom Add-ons

To write a custom add-on, you should create a directory and in it create at least one text file with the extension .addon, for example admin-role.addon.

This file needs to contain the Name and Description metadata fields, as well as the commands that you want to execute as a part of the add-on.

The following example shows the definition of an add-on that gives the developer user cluster-admin privileges.

Example: Add-on definition for admin-role
# Name: admin-role
# Description: Gives the developer user cluster-admin privileges

oc adm policy add-role-to-user cluster-admin developer

After you define the add-on, you can install it by running:

$ minishift addons install <ADDON_DIR_PATH>
You can also edit your add-on directly in the Minishift add-on install directory $MINISHIFT_HOME/addons. Be aware that if there is an error in the add-on, it will not show when you run any addons commands, and it will not be applied during the minishift start process.