Add-ons

Overview

Minishift allows you 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)
# OpenShift-Version: >3.6.0                                                             (4)
# Minishift-Version: >1.22.0                                                            (5)
mytoken := oc sa get-token oauth-client                                                 (6)
oc new-app -p OPENSHIFT_OAUTH_CLIENT_SECRET=#{mytoken}                                  (7)
oc adm policy add-scc-to-group anyuid system:authenticated                              (8)

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

OpenShift-Version Semantics

As part of the add-on metadata you can specify the OpenShift version which needs to be running in order to apply the add-on. To do so, you can specify the optional OpenShift-Version metadata field. The semantics are as follows:

Minishift-Version Semantics

As part of the add-on metadata you can specify the Minishift version which needs to be running in order to apply the add-on. To do so, you can specify the optional Minishift-Version metadata field. The semantics are as follows:

Defining Add-on Dependencies

Add-on dependencies can be defined using the Depends-On metadata field. Multiple dependencies may be defined using a comma-separated list of add-on names.

Example: Defining add-on dependency in add-on definition file

# Name: example
# Description: Shows the use of Depends-On tag
# Depends-On: anyuid, admin-user
# This add-on depends on anyuid and admin-user add-on
echo Depends on anyuid, admin-user add-on, and requires them to be installed

Add-on Commands

This section describes the commands that an add-on file can contain. They form a small domain-specific language 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 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.

openshift

If the add-on command starts with openshift, it uses the oc binary present in the OpenShift container to execute the command. 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.

cat

If the add-on command starts with cat, the arguments following the cat command should be a valid file path. This will print the file content to the console for valid file otherwise displays error message about the non-existence of file. This can be useful in case you want to use a file content with other command.

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.

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

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)

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

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

You can also provide default values for variables using the Var-Defaults metadata header. Var-Defaults needs to be specified in the format of <key>=<value>. Multiple default key/value pairs need to be comma separated.

# Name: acme
# Description: ACME add-on
# Required-Vars: PROJECT_USER
# Var-Defaults: PROJECT_USER=john

Internal Variables

Add-on allows to define variables in an add-on. These variables can be used to store output of an add-on command.

For example, you can save a oc command output in a variable mytoken and use it in the subsequent add-on commands.

example :

mytoken := oc sa get-token oauth-client
oc new-app -p OPENSHIFT_OAUTH_CLIENT_SECRET=#{mytoken}

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.

Add-ons by the Community

Apart from the several default add-ons, there are a number of community developed add-ons for Minishift. Community add-ons can be found in the minishift-addons repository. You can get all the information about these add-ons in the repository. The instructions for installing them can be found in the README.

Installing Add-ons

Add-ons are installed with the minishift addons install command.

The following example shows how to install an add-on.

Example: Installing an add-on

$ minishift addons install <path_to_addon_directory>

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)

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

Removing Add-ons

Add-ons can be removed with the minishift addons remove command. It is the mirror command to minishift addons apply and similarly can be used regardless whether the add-on is enabled or not. Provided the specified add-on is installed and has a <addon_name>.addon.remove file, minishift addons remove will execute the commands specified in this file.

To remove multiple add-ons with a single command, specify the add-on names separated by space. The following example shows how to explicitly remove the admin-user add-on.

Example: Removing admin-user add-on

$ minishift addons remove admin-user
-- Removing addon 'admin-user':.
admin user deleted

Uninstalling Add-ons

Add-ons can be uninstalled with the minishift addons uninstall command. It is the mirror command to minishift addons install and can be used regardless whether the add-on is enabled or not. Provided the specified add-on is installed, minishift addons uninstall will delete the corresponding add-on directory from $MINISHIFT_HOME/addons.

The following example shows how to explicitly uninstall the admin-user add-on:

Example: Uninstalling admin-user add-on

$ minishift addons uninstall admin-user
Add-on 'admin-user' uninstalled

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>

# Name: prometheus
# Description: This template creates a Prometheus instance preconfigured to gather OpenShift and
# Kubernetes platform and node metrics and report them to admins. It is protected by an
# OAuth proxy that only allows access for users who have view access to the prometheus
# namespace. You may customize where the images (built from openshift/prometheus
# and openshift/oauth-proxy) are pulled from via template parameters.
# Url: https://prometheus.io/

To provide add-on remove instructions, you can create text file with the extension .addon.remove, for example admin-user.addon.remove. Similar to the .addon file, it needs the Name and Description metadata fields. If a .addon.remove file exists, it can be applied via the remove command.