Using modules

See Modules for a detailed explanation about modules and how to enable them.

Quick start - my-infraxys-by-example module

We’ll create an empty GitHub repository and connect it to Infraxys Developer. This procedure is enough for the module-setup in Infraxys-by-example.

  • Create a new repository in GitHub. Make it public and check the option to create a readme.md-file.
  • In Infraxys Developer, right-click in the modules-tree on the right and select “Add module” from the context menu.
  • Enter the HTTPS-URL or GIT-URL to the repository. You can retrieve this from the home-page of the repository by clicking on the “Code”-button (ie https://github.com/jeroenmanders/my-infraxys-by-example.git).

We need to provide a token for HTTPS-URLs or an SSH-Keypair if we want to push updates to the repository from GitHub, or if this is a GitHub Enterprise instance. See the “Add module”-dialog in Infraxys for details.

If you get an error similar to TransportException occurred in fetchGitBranches org.eclipse.jgit.api.errors.TransportException: https://github.com/jeroenmanders/my-infraxys-by-example.git: https://github.com/jeroenmanders/my-infraxys-by-example.git/info/refs?service=git-upload-pack not found: Not Found, then this means that the provided token doesn’t have access to the repository.

Detailed setup: Creating a module with packets

In this example we’ll create a module with common functionality. For documentation purposes, we’ll make this module private so we need to configure a deploy key to grant Infraxys read-rights.

An Infraxys application server will automatically update packets and a provisioning server will update module sources when changes are pushed to configured GitHub branches. If you don’t want to or cannot use webhooks, then updates can be pulled through a context-menu, which is documented in the “Attach dev-branch to Infraxys” part below.

We’ll use the “infraxys-modules” GitHub organization in this step-by-step example with branches “dev” and “prod”. You’ll need to change the GitHub-organization and repository name to your needs.

All resources are available in the public examples-repository which you can use directly: git@github.com:infraxys-modules/examples.git.

Prerequisites

If you want to enable GitHub webhooks, then the GitHub hook-IP-ranges can contact your Infraxys application and the provisioning server(s) on the configured ports.

https://api.github.com/meta contains the ip-addresses used by GitHub hooks.

/opt/infraxys/docker-webhook/stack.yml on the provisioning servers contain a variable called “WEBHOOK_SECRET”, You’ll need these values below.

You should have been assigned grant ‘module.add’ in Infraxys.

Create the GitHub-repository

  • Create a new GitHub-repository “commons”.
  • Create a directory on your workstation and execute the following code:
echo "# commons" >> README.md
git init
git checkout -b dev
git add README.md
git commit -m "first commit"
git remote add origin git@github.com:infraxys-modules/commons.git
git push -u origin dev

Configure Infraxys

  • In the Infraxys web-UI, open the right slider-window.
  • Open the Modules-tab.
  • Right-click in the modules-list and select “Add module”.
  • Enter the SSH-url (https-url if the repository is public. No key pair is needed in this case)
  • If you already have a key-pair defined for the Git-organization, then select the key from the dropdown, otherwise:
    • Click “Generate” to generate a key pair.
    • Copy the public key to your clipboard.
    • In the commons-GitHub repository, open the settings-page.
    • Click “Deploy keys” and then “Add deploy key”.
    • Enter a name for the key and paste the public key in the Key-field.
    • Infraxys is not supposed to write to the repository, so don’t select the “Allow write access” option.
    • Click “Add key”. You probably need to enter your GitHub-password after this step.
  • Click on the Webhooks-link.
  • Click “Add webhook”.
  • Enter the URL where your Infraxys application server can be reached by GitHub followed by the port if required and /webhooks/github.
  • Make sure “application/json” is selected for the content type.
  • Leave the other options as is. We’re only interested in push-events.
  • Click the “Add webhook”-button.
  • There should be a mark in front of the webhook indicating that the delivery was successful.

Leave this GitHub webhooks page open for the provisioning servers configuration.

Attach dev-branch to Infraxys

We’ll now specify that we want to import the resources that are configured in the dev-branch.

  • Return to the modules-screen in Infraxys and click on the “Branches”-button.
  • If Infraxys can reach the GitHub-instance, the deploy-key was created correctly and the dev-branch exists, then the dev-branch will be in the right list.
  • Right click on “dev” and then “Connect and import branch”:
  • Infraxys will try to import packets and roles from the module.
  • Click “Finish”.

Provisioning servers

This step only needs to be done if provisioning servers are located on separate machines.

Every provisioning server is configured separately so that you can choose which modules and branches will be available.

Configure the module branch

  • Open the provisioning server container (initially under environment Core/Root)
  • Activate tab “Modules”.
  • Drag and drop the “dev”-branch from the right slider in the modules-table of the provisioning server.
  • Pull the latest changes through the context menu of this new module-link.
  • Infraxys will connect to the provisioning server and clone the repository branch if it’s not already there. Otherwise it will run “git pull”.
  • This action can be used instead of webhooks, every time changes need to be applied to the repository on the provisioning server.

Configure the webhook

Just like with the packets, it’s not required to configure webhooks. You can manually update the provisioning servers through a context-menu.

  • Click again on the “Add webhook”-link in the GitHub webhooks-page.
  • Specify the url (and port if needed) where GitHub can reach the provisioning server and add /hooks/webhook to it.
  • Make sure “application/json” is selected for the content type.
  • Leave the other options as is. We’re only interested in push-events.
  • Click the “Add webhook”-button.
  • The webhook should contain a mark that the last delivery was successful.

Populating the module

Module code and package definitions can be written using your favorite IDE., but packet and attribute definitions are easiest using the Infraxys UI.

Creating packet “Name value”

This packet can be used to store arbitrary configuration information. An example would be that your company has some fixed IP-ranges that need to be whitelisted in several locations. You would create one instance on a shared container and enter the IP CIDRs as a comma separated list in the value-field. Specifying Velocity name “globalWhiteList” allows you to use this list anywhere in Infraxys by specifying Velocity string $globalWhitelist.getAttribute("value").

Open the Infraxys UI on your workstation or a server installation and perform the following steps:

  • Create a new packet and name it “String value”.
  • Instance label: “%instance_label%” (this will show the value of attribute “instance_label” in the instance trees).
  • Global unique id: “String value” (the value is not important here, but it should be unique in the Infraxys-environment that you’re working in)
  • Click “Save”.
  • Create 2 string attributes. Only the fields in the screenshots are important for these: For the purpose of this example, we’ll add an action to this packet:
  • Click the files-tab of the packet and create a new file through the context-menu of the files-table.
  • Name: Show value
  • Filename: show_value.sh
  • Parse with Velocity: check
  • Executable: Check
  • Menu path: My/Submenu
  • File contents:
#!/usr/bin/env bash -eo pipefail

# call function "show_string_value" in the examples-module. We could
#    call the show_message_dialog here directly as well.

show_string_value --title "$instance_label.toUpperCase()" --message "Attribute '$instance_label' has value '$value'.";
  • Click Save

GitHub files

We now need to create the files in our GitHub repository. This is done through the context-menu of the module-branch in the Modules-tree table.

  • Under the directory where the dev-branch is checked out, create a directory “auto-source”. Files in this directory will automatically get sourced before any other code of the action is executed. This is done for every enabled module. See https://en.wikipedia.org/wiki/Source_(command) for more information.
  • Create file “/auto-source/string_value.sh” (name is not important) and paste the following code in it:
show_string_value --title "My title" --message "My message"<br>function show_string_value() {<br>    local function_name="show_this_message" title message;<br>    import_args "$@"; # populate local variables and name them as the argument name<br>                      # (--title 'title' creates a local variable called 'title')<br>    check_required_arguments "$function_name" title message; # exit with error if one of these 2 variables is empty<br><br>    show_message_dialog --title "$title" \<br>        --message "$message";<br>}<br>
  • Right-click the module branch.
  • Select the option to save, commit and push the changes.
  • After pushing the code, two webhooks will be fired:
  • One webhook will update the module-files on the provisioning server.
  • Another will import the new packet into Infraxys. Subsequent pushes will merge the changes. Packets that are removed from GitHub will be removed from Infraxys only if they aren’t in use.

Your module-tree now contains the packet. Adding roles is done in the same way.

Testing the module and packet

You can drag the “String value”-packet from the dev-branch to instance trees on containers:

  • create a container in any environment.
  • Give it a name and description (ie examples/examples).
  • Open the instances-tab.
  • Drag the “String value” tree-item and drop it in the instance tree
  • Instance label: Whitelist 1
  • Value: 10.0.0.0/8,192.168.0.0/16
  • Velocity name: myWhitelist
  • Click “Save”.
  • Drag another instance anywhere in the instance tree on any container of the current environment (or another environment where above container is shared)
  • Instance label: From myWhitelist
  • Value: $myWhitelist.getAttribute(“value”)
  • Click “Save”.
  • Click “Generate scripts”.
  • Right-click the “From myWhitelist”-instance, actions -> My -> Submenu -> Show value.
  • An SSH-session to the provisioning server is opened, then a Docker container is started with the enabled modules for the current packet. After bootstrapping, the action is run and it calls a function from the module which shows the following dialog: