Chapter 5. Add-ons
5.1. Add-ons Overview
This feature is still considered experimental and might change in future releases.
Minishift allows to configure the vanilla OpenShift setup provided by cluster up with an add-on mechanism.
Add-ons are directories that contain one or more text files with the addon extension. The directory can also have other resource files such as JSON template files. However, only one addon file is allowed.
Example: anyuid add-on definition file
This example shows the contents of the add-on text file, including the name and description of the add-on, additional metadata, and the actual commands to run.
# Name: anyuid 1 # Description: Allows authenticated users to run images under a non pre-allocated UID 2 oc adm policy add-scc-to-group anyuid system:authenticated 3
- 1
- (Required) Name of the add-on.
- 2
- (Required) Description of the add-on.
- 3
- Actual add-on command. In this case, the command executes the oc binary. For the full list of the supported add-on commands, see the Section 5.1.1, “Add-on Commands” section.
Comment lines can be inserted at anywhere in the file. Comment lines must start with the '#' character.
Enabled add-ons are applied during minishift start, immediately after the initial cluster provisioning successfully completes.
5.1.1. Add-on Commands
This section describes the command types that an add-on file can contain and what the commands do. The following command types are available forming a sort of mini-DSL for 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 sshand then executing any command on the VM. - oc
If the add-on command starts with oc, it uses the oc binary that is cached on your host to execute the specified
occommand. This is similar to runningoc --as system:admin …from the command-line.NoteThe
occommand is executed as system:admin- openshift
-
If the add-on command starts with openshift, you can run the
openshiftbinary 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
dockercommand 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 runningeval $(minishift docker-env)on your host and then executing anydockercommand. - 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
ocmight take a few seconds before a certain resource can be queried.
Trying to add a command that is not listed will cause an error when the add-on gets parsed.
5.1.2. Variable Interpolation
Minishift also allows the use of variables as part of the supported commands. Variables have the form #{<variable-name>}. Example: Usage of the routing suffix variable shows how the routing suffix can be interpolated into a openshift command to create a new certificate as part of securing the OpenShift registry.
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
Table 5.1, “Supported add-on variables” shows the currently supported variables which are available for interpolation.
| Variable | Description |
|---|---|
| ip | The IP of the Minishift VM |
| routing-suffix | The OpenShift routing suffix for application |
| addon-name | The name of the current add-on |
5.1.3. 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=trueThis 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.
5.2. Enabling and Disabling Add-ons
Add-ons are enabled with the minishift addons enable command and disabled with the minishift addons disable command.
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
5.2.1. Add-on Priorities
When you enable an add-on, you can also specify a priority as seen in Example: Enabling the registry add-on with priority.
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.
Example: List command output with explicit priorities
~]$ minishift addons list
- anyuid : enabled P(0)
- registry : enabled P(5)
- eap : enabled P(10)
In Example: List command output with explicit priorities, the anyuid, registry, and eap add-ons are enabled with the respective priorities of 0, 5 and 10. This means that anyuid gets applied first, followed by registry, and lastly the eap add-on.
If two add-ons have the same priority the order in which they are getting applied is not determined.
5.2.2. 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 as well as the commands that you want to execute as a part of the add-on. Example: Add-on definition for admin-role shows the 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.
