# 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) oc adm policy add-scc-to-group anyuid system:authenticated (5)
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.
# 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) oc adm policy add-scc-to-group anyuid system:authenticated (5)
| 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 Semantic |
| 5 | 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. |
Enabled add-ons are applied during minishift start, immediately after the initial cluster provisioning is successfully completed.
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>. |
This section describes the commands that an add-on file can contain. They form a small domain-specific language for Minishift add-ons:
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.
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 |
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.
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.
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.
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. |
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.
$ 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
There exist several built-in variables which are available for interpolation at all times. The following table shows these 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. |
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 |
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
|
|
|
Variable values specified via the command line using the |
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-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. |
xpaas |
Imports xPaaS templates. |
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.
Add-ons are installed with the minishift addons install command.
The following example shows how to install an add-on.
$ minishift addons install <path_to_addon_directory>
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.
$ minishift addons enable anyuid
$ minishift addons disable anyuid
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.
$ 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.
$ 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. |
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.
$ minishift addons apply anyuid admin-user
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.
$ minishift addons remove admin-user -- Removing addon 'admin-user':. admin user deleted
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:
$ minishift addons uninstall admin-user Add-on 'admin-user' uninstalled
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.
# 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 |
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.