Repository

This document describes the Rundeck Repository features, which allow you to install plugins from the official Rundeck Repository, or to configure your own repositories for serving plugins to your own private installation.

You can use the repositories to find plugins using the "Find Plugins" entry under the Plugins menu that is accessed from the gear icon in the GUI. You can also use the rd tool to install, uninstall, and upload plugins that are saved in these repositories.

Prerequisites

In order to use the official Rundeck Repository your Rundeck server must be allowed to connect to the internet and to access https://api.rundeck.com based urls.
If you do not wish to allow your Rundeck server to reach the internet you can still use the private repository features, but the official Rundeck repository will be unavailable to you, and should be disabled.

Enabling the Repository feature

To enable the repositories. Add the flag:

rundeck.feature.repository.enabled=true

to your rundeck-config.properties file.

GUI Usage

Each repository that is enabled will show up in the Rundeck user interface when you click the gear icon then go to Plugins>Find Plugin.

When you go to the plugin page you will see each repository and the plugins they provide.

The plugins are each represented by a card. The following image explains the content of the plugin card.

If you have the official repository enabled you will see some plugins with an install button. These plugins can be immediately installed by clicking the Install button. When the plugin is installed, it will be pulled from the Rundeck repository and copied into the correct location in your Rundeck installation. After installation, it is ready for immediate use. Some plugins do not have an install button. Manual installation is required for those plugins. To install those plugins you need to click on the source link icon , which will take you to the plugins source page, and there you can check for instructions regarding the install of that plugin.

Installable plugins are also un-installable. Just click the Uninstall button to uninstall the plugin. This will delete the plugin from the correct location immediately.

All plugins that you add to your private repository are installable and un-installable from the GUI.

Configuration

When you enable the Rundeck Repository the following default files and directories are created for you:

RDECK_BASE/server/config/artifact-repositories.yaml - Repositories are configured in this file.
RDECK_BASE/repository/artifacts - The directory into which your private plugins will be copied when you use the upload command to build your private plugin repository.
RDECK_BASE/repository/installedPlugins - The directory into which plugins will be copied when you use install them either from the official Rundeck repository or your private repository.

Both the artifacts and installedPlugins locations are configurable using the storage tree mechanism.

Installed Plugin Storage

When you install a plugin from a repository into your Rundeck instance, the plugin will be copied into the libext folder as usual. The plugin will also be copied to a location
that you can configure using the storage tree mechanism. Optionally, the location can be a central location all of your Rundeck instances share which can keep the plugins they have installed in sync.
You can only have one location specified for storing installed plugins.

The following examples show how to configure the installed plugin location:

Save installed plugins to your local filesystem at the location: /opt/repository/installedPlugins

rundeck-config.properties

rundeck.repository.plugins.provider.1.type=file
rundeck.repository.plugins.provider.1.path=/
rundeck.repository.plugins.provider.1.config.baseDir=/opt/repository/installedPlugins

Save installed plugins to your local filesystem at the location: /opt/repository/content/installedPlugins

rundeck-config.properties

rundeck.repository.plugins.provider.1.type=file
#This must match the storageTreePath below
rundeck.repository.plugins.provider.1.path=/installedPlugins
rundeck.repository.plugins.provider.1.config.baseDir=/opt/repository

#Must match the path previously specified in the storage tree configuration
rundeck.feature.repository.installedPlugins.storageTreePath=/installedPlugins

Note: In the example above the storage tree path was not the default '/' root location, therefore the extra property:
rundeck.feature.repository.installedPlugins.storageTreePath was required. This property is not required if the '/' default root is used.

Save installed plugins to a Minio object store

rundeck-config.properties

rundeck.repository.plugins.provider.1.type=object
rundeck.repository.plugins.provider.1.path=/
rundeck.repository.plugins.provider.1.config.bucket=repository
rundeck.repository.plugins.provider.1.config.objectStoreUrl=http://your-minio-server:9000
rundeck.repository.plugins.provider.1.config.secretKey=YOUR_SECRET_KEY
rundeck.repository.plugins.provider.1.config.accessKey=YOUR_ACCESS_KEY

Save installed plugins to a Minio object store for cluster where all members sync their plugins on bootstrap

rundeck-config.properties

rundeck.repository.plugins.provider.1.type=object
rundeck.repository.plugins.provider.1.path=/
rundeck.repository.plugins.provider.1.config.bucket=repository
rundeck.repository.plugins.provider.1.config.objectStoreUrl=http://your-minio-server:9000
rundeck.repository.plugins.provider.1.config.secretKey=YOUR_SECRET_KEY
rundeck.repository.plugins.provider.1.config.accessKey=YOUR_ACCESS_KEY
#Set this property so that the object store directory will not be cached on the Rundeck instance
#rundeck.repository.artifacts.provider.1.config.uncachedObjectLookup=true
#This cluster member will pull it's plugins from the installed plugin location and install them when it bootstraps
rundeck.feature.repository.syncOnBootstrap=true

Repositories

Repositories are locations that store plugin jar and zip files that may be installed into a Rundeck instance.

Here are some examples for various configurations of private artifact repositories.

Filesystem

Save private repository plugin artifacts to your local filesystem at the location: /opt/repository/content/artifacts

rundeck-config.properties

rundeck.repository.artifacts.provider.1.type=file
rundeck.repository.artifacts.provider.1.path=/artifacts
rundeck.repository.artifacts.provider.1.config.baseDir=/opt/repository

artifact-repositories.yaml

-   repositoryName: Private
    type: STORAGE_TREE
    configProperties:
        storageTreePath: /artifacts

Object Store

Save private repository plugin artifacts to a minio object store

rundeck-config.properties

rundeck.repository.artifacts.provider.1.type=object
rundeck.repository.artifacts.provider.1.path=/minio
rundeck.repository.artifacts.provider.1.config.bucket=repository
rundeck.repository.artifacts.provider.1.config.objectStoreUrl=http://your-minio-server:9000
rundeck.repository.artifacts.provider.1.config.secretKey=YOUR_SECRET_KEY
rundeck.repository.artifacts.provider.1.config.accessKey=YOUR_ACCESS_KEY

artifact-repositories.yaml

-   repositoryName: MinioRepo
    type: STORAGE_TREE
    configProperties:
        storageTreePath: /minio

Use a file store for one repo and an object store for another

rundeck-config.properties

rundeck.repository.artifacts.provider.1.type=file
rundeck.repository.artifacts.provider.1.path=/repo1
rundeck.repository.artifacts.provider.1.config.baseDir=/opt/repository

rundeck.repository.artifacts.provider.2.type=object
rundeck.repository.artifacts.provider.2.path=/minio
rundeck.repository.artifacts.provider.2.config.bucket=repository
rundeck.repository.artifacts.provider.2.config.objectStoreUrl=http://your-minio-server:9000
rundeck.repository.artifacts.provider.2.config.secretKey=YOUR_SECRET_KEY
rundeck.repository.artifacts.provider.2.config.accessKey=YOUR_ACCESS_KEY

artifact-repositories.yaml

-   repositoryName: Repo1
    type: STORAGE_TREE
    configProperties:
        storageTreePath: /repo1
-   repositoryName: Repo2
    type: STORAGE_TREE
    configProperties:
        storageTreePath: /minio

Using the repositories with the `rd` tool

The rd tool can be used to list plugins, install plugins from a repository, upload to a private repository, and uninstall plugins.

List Plugins

rd plugins

==Official Repository==
2e51ce08c836 : rundeck-http-workflow-step-plugin : 1.0.11 (not installed)
def44eeac568 : nixy-local-steps : v1.2.6 (installed)
ee1e33e004e0 : nixy-file : v1.2.6 (not installed)
681c33f5c3fd : openssh-bastion-host : 1.0.0 (installed)
86177619503e : slack-notification-plugin : 1.2.6 (not installed)
1d56241b6d14 : rundeck-azure-storage-plugin : 1.0.0 (not installed)
5c3a72ab196c : http-notification-plugin : 0.1.0-SNAPSHOT (installed)  (Updateable to 1.0.5)
452e4837ebb6 : jira-notification-2 : 1.0.1 (not installed)
15712f2421d1 : kubernetes-plugin-2 : 1.0.0 (installed)  (Updatable to 1.0.12)
59ed572534b2 : py-winrm-plugin : 1.0.7 (installed)  (Updateable to 2.0.1)
01a78578d6d9 : hashicorp-vault : 1.3.0 (installed)
d8a7e2981805 : s3-log-storage-plugin : 1.0.7 (installed)
d4338c89f3f6 : nixy-step-plugin-waitfor : v1.2.6 (not installed)
904beafe241b : aws-s3-step-plugin : 1.2.1 (installed)
765bd99fd03b : puppet-apply-step : 1.0 (installed)
f39ba031afe7 : rundeckansible : 3.0.1 (not installed)
7b324410cef0 : rundeck-ec2-nodes-plugin : 1.5.10 (not installed)
01a78578d6d9 : vault-storage : 1.3.0 (installed)
36cc72f36df7 : jq-json-log-filter : 1.0.2 (not installed)
3eb57b31591f : rundeck-winrm : 1.3.5 (installed)
55e70e8b52d7 : rundeck-rainbow : 0.1.2 (installed)
681c33f5c3fd : openssh-bastion-host-node-execution : 1.0.0 (installed)
904beafe241b : aws-cli-plugin : 1.2.1 (installed)
ac67623a4999 : pagerduty-notification : 1.2.1 (not installed)
fa61f23b7a1c : jira-workflow-step : 1.0.1 (not installed)
==Private Repository==
01843c9fbe3d : Icon Nodes Enhancer : 0.1.4-SNAPSHOT (not installed)

Install Plugin

This would install the Icon Node Enhancer plugin listed previously

rd plugins install -r Private -i 01843c9fbe3d

Plugin Installed

Uninstall Plugin

This would uninstall the Icon Node Enhancer plugin that was previously installed

rd plugins uninstall -i 01843c9fbe3d

Plugin Uninstalled

Upload Plugin

To upload a plugin into your private plugin repository execute:

rd plugins upload -r Private -f /path/to/your/plugin.jar

rd plugins upload -r Private -f /path/to/your/plugin.zip

which will give you the message:

Upload succeeded

At this time only java and script plugin types are uploadable into a repository

How to disable a repository

If you need to disable a repository for some reason, but would like to retain the entry in your
artifact-repositories.yaml file, you can add an enabled: false property to the repository
entry and it will be disabled. Once disabled, the repository will no longer show up in the Find Plugins GUI or
when using the rd tool.

Example:

-   repositoryName: Private
    enabled: false
    type: STORAGE_TREE
    configProperties:
        storageTreePath: /artifacts