1. Basics

Foreman Azure allows you to provision and manage your hosts in Azure. This is convenient when you want your users to have restricted access to your Azure account (such that only they can create hosts), to monitor and configure them automatically (via Ansible, Puppet, etc..), or also to automate its creation via host groups.

This plugin 1.x series should be compatible with Foreman 1.11, 1.12 and 1.13. Future versions of Foreman might or might not be compatible. 2.x will be released when the plugin is found to not be compatible with any of these 3 versions or drops compatibility of any of them.

2. Installation

See the Foreman manual.

Red Hat, CentOS, Scientific Linux (rpm)

Set up the repo as explained in the link above, then run

# yum install tfm-rubygem-foreman_azure

Fedora (rpm)

Set up the repo as explained in the link above, then run

# yum install rubygem-foreman_azure

Debian, Ubuntu (deb)

Set up the repo as explained in the link above, then run

# apt-get install ruby-foreman-azure

Bundle (gem)

Add the following to bundler.d/Gemfile.local.rb in your Foreman installation directory (/usr/share/foreman by default)

$ gem 'foreman_azure'

Then run bundle install from the same directory

3. Configuration

Same as any other compute resource, provide your credentials:

Azure credentials

Then associate your Foreman operating system with an image on Azure. The username is not important, Foreman will instruct Azure to setup that name for SSH login using the Azure certificate:

Azure image

And you’ll be able to create hosts in Azure with that image and many other options, via Foreman. This will allow you to proactively manage your hosts DHCP/DNS, configuration management, parameters, run scripts via remote execution and more!

Azure options on new host

When you create the compute resource, you need to provide your subscription ID, a path to the .pem certificate, and a URL to your Azure API. Read below how to create the certificate needed.

Certificate creation

The certificate used must be generated by the user. OpenSSL can be used to create the management certificates. Two certificates are needed: a .cer file, which is uploaded to Azure, and a .pem file, which is stored locally.

To create the .pem file, execute the following command:

openssl req -x509 -nodes -days 365 -newkey rsa:1024 -keyout /etc/foreman/azure.pem -out /etc/foreman/azure.pem

To create the .cer file, execute the following command:

openssl x509 -inform pem -in /etc/foreman/azure.pem -outform der -out /etc/foreman/azure.cer

After creating these files, the .cer file will need to be uploaded to Azure via the “Upload a Management Certificate” action of the “Management Certificates” tab within the “Settings” section of the classic management portal. Read how to upload the certificate on the Azure official documentation.

Management certificate upload

4. Usage

This plugin works no matter if you have a Foreman smart-proxy in Azure or not. If you do have a smart-proxy that manages DHCP/DNS/TFTP in the same Azure network as the hosts you intend to create, you will be able to PXE boot and discover hosts in that network. Read more about smart-proxy installation on the manual.

If you do not have a smart-proxy in the Azure network you want to provision, Foreman will use SSH provisioning using the Azure certificate in the compute resource, and the name in the image. If you’ve set ‘foo’ as the username for your image, you can SSH into it by calling ssh -i path_to_your_azure_cert foo@azurehost. Your OS must be associated with a ‘finish’ template in order to provision through SSH. This template will be sent via SSH to your host after it’s created and it will provision the host.

At the moment, Azure hosts have a domain ‘cloudapp.net’ by default. You can create a ‘cloudapp.net’ domain (without DHCP/DNS proxies) and assign it to your Azure hosts.

Alternatively, if you do not want your hosts to show up with the ‘cloudapp.net’ domain in Foreman, you can do the following. Foreman does not yet allow domainless provisioning. This means you will have to create a ‘fake domain’ without subnets in Foreman, and set your interfaces as ‘unmanaged’ when you create your host. This will tell Foreman to not create DHCP/DNS records for this host, and it will let Azure do that. Notice the red circles in the picture, these show a fake domain with no subnets, and the managed checkbox:

interfaces unmanaged interface

When the host finishes provisioning, the public IP and interfaces from Azure will show up in Foreman.

5. Help

Please follow our standard procedures and contacts.

5.1 Troubleshooting

Errors regarding the provisioning will show up on /var/log/foreman/production.log of your Foreman host.

If you find a bug, please file it in Redmine.

See the troubleshooting section in the Foreman manual for more info.

5.2 Contributing

Follow the same process as Foreman for contributing.

Sources at github.com/theforeman/foreman_azure

The 2021 community survey is now live! Please take a few minutes to fill it out and help us make Foreman better!

Foreman 3.0.0 has been released! Follow the quick start to install it.

Foreman 2.5.4 has been released! Follow the quick start to install it.

Foreman 2.4.1 has been released! Follow the quick start to install it.