1. Documentation
×

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)
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 (Optional) OpenShift version required to run a specific add-on. See OpenShift Version Semantics
5 (Optional) Minishift version required to run a specific add-on. See Minishift Version Semantics
6 Run an actual add-on command and store its output in a variable. See Internal Variable
7 Actual add-on command. In this case, the command executes the oc binary using the mytoken variable value.
8 Actual add-on command. In this case, the command executes the oc binary.

  • Comment lines, starting with the '#' character, can be inserted anywhere in the file.

  • Command starting with ! character ignores the execution failure. With the help of this, add-on will be idempotent i.e. a command can be executed multiple times without changing the final behavior of the add-on.

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:

>3.6.0

OpenShift version higher than 3.6.0 needs to be running in order to apply the add-on.

>=3.6.0

OpenShift version 3.6.0 or higher needs to be running in order to apply the add-on.

3.6.0

OpenShift version 3.6.0 needs to be running in order to apply the add-on.

>=3.5.0, <3.8.0

OpenShift version should higher or equal to 3.5.0 but lower than 3.8.0.

>=3.5.0, <=3.8.0

OpenShift version should higher or equal to 3.5.0 but lower or equal to 3.8.0.

If the metadata field OpenShift-Version is not specified in the add-on header, the add-on can be applied against any version of OpenShift.

OpenShift-Version only supports versions in the form of <major>.<minor>.<patch>.

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:

>1.22.0

Minishift version higher than 1.22.0 needs to be running in order to apply the add-on.

>=1.22.0

Minishift version 1.22.0 or higher needs to be running in order to apply the add-on.

1.22.0

Minishift version 1.22.0 needs to be running in order to apply the add-on.

>=1.21.0, <1.25.0

Minishift version should higher or equal to 1.21.0 but lower than 1.25.0.

>=1.22.0, <=1.25.0

Minishift version should higher or equal to 1.22.0 but lower or equal to 1.25.0.

If the metadata field Minishift-Version is not specified in the add-on header, the add-on can be applied against any version of Minishift.

Minishift-Version only supports versions in the form of <major>.<minor>.<patch>.

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.

The oc command is executed as system:admin.
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.

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.

user

User used by Minishift for execution of commands through ssh.

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 command 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, 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 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

= and , are metacharacters and cannot be used as part of keys or values.

Empty value will be set if NULL, Null or null specified as value for a _Var-Defaults key.

# Var-Defaults: PROJECT_USER=null

Variable values specified via the command line using the --addon-env or set via minishift config set addon-env have precedence over Var-Defaults.

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.

Table 2. Default add-ons
Add-on Name Description

anyuid

Changes the default security context constraints to allow pods to run with arbitrary UID.

admin-user

Creates a user named 'admin' and assigns the cluster-admin role to it.

registry-route

Creates an edge terminated route for the OpenShift registry.

htpasswd-identity-provider

User can change and add default login username and password for the OpenShift instance.

admissions-webhook

Enables validating and mutating admission webhooks.

xpaas

Imports xPaaS templates.

redhat-registry-login

Creates secret to access images on registry.redhat.io.

che

Deploy che on the Minishift.

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)

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

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>

You can also write metadata with multiple lines.

Example: Add-on definition which contain multiline description
# 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/

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.

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.